NAV Navbar
5.4.3
shell
MORPHEUS API

Introduction

Welcome to the Morpheus API Documentation.

Morpheus is a powerful cloud management tool that provides provisioning, monitoring, logging, backups, and application deployment strategies.

This document describes the Morpheus API protocol and the available endpoints. Sections are organized in the same manner as they appear in the Morpheus UI.

Sections

Section Description
Authentication Get Access Token, Refresh Access Token, Whoami, Forgot Password
Operations Dashboard, Reports, Wiki, Budgets, Approvals, Activity, Usage, Billing, Invoices, History, Health, Guidance
Provisioning Instances, Apps, Blueprints, Jobs, Automation, Virtual Images, Library, Deployments, Deploys
Infrastructure Groups, Clouds, Clusters, Hosts, Networks, Load Balancers, Storage, Keys & Certs
Logs View logs for your hosts and containers.
Monitoring Checks, Incidents, Alerts, Contacts
Tools Cypher, Archives, Image Builder, Self Service, VDI Pools
Personas Service Catalog, Virtual Desktop
Administration Tenants, Roles, Users, Identity Sources, Integrations, Plans & Pricing, Policies, Settings, License, Ping, Setup

To initialize a freshly installed Morpheus appliance, see Setup.

Version

You can determine your current version using Ping.

curl "$serverUrl/api/ping"

The above command returns JSON structured like this:

{
  "success": true,
  "buildVersion": "5.3.0.184",
  "applianceUrl": "$serverUrl",
  "setupNeeded": false
}

API

The Morpheus API is an HTTP interface for interacting with the Morpheus appliance. It provides a RESTful interface where GET reads, POST creates, PUT updates and DELETE destroys resources.

curl "$serverUrl/api/users/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "user": {
    "id": 1,
    "accountId": 1,
    "username": "admin",
    "displayName": "Morpheus Admin",
    "email": "admin@morpheusdata.com",
    "firstName": "Morpheus",
    "lastName": "Admin",
    "enabled": true,
    "receiveNotifications": true,
    "isUsing2FA": true,
    "accountExpired": false,
    "accountLocked": false,
    "passwordExpired": false,
    "loginCount": 42,
    "loginAttempts": 0,
    "lastLoginDate": "2021-04-17T00:12:01Z",
    "roles": [
      {
        "id": 1,
        "authority": "System Admin",
        "description": "Super User"
      }
    ],
    "account": {
      "id": 1,
      "name": "morpheusdata.com"
    },
    "linuxUsername": "morphadmin",
    "linuxPassword": null,
    "linuxKeyPairId": 5,
    "windowsUsername": "morphadmin",
    "windowsPassword": "************",
    "defaultPersona": {
      "id": 1,
      "code": "standard",
      "name": "Standard"
    },
    "dateCreated": "2016-08-27T19:28:09Z",
    "lastUpdated": "2021-04-17T00:12:01Z"
  }
}

This is an example of a Morpheus API request that retrieves details about a User.

HTTP Request

GET $serverUrl/api/users/:id

HTTP Request describes the method and path of the endpoint. Most endpoints have a path formatted as /api/:resources/:id.

URL Parameters

Parameter Description
:id ID of the User.

URL Parameters are variables which are included inside the path of the request.

HTTP Headers

Header Description
Authorization Use the format BEARER ${access_token}. Example: Authorization: BEARER e1d62c34-f7f5-4713-a874-31491e7707de. Most endpoints require this header. Some exceptions include Authentication and Setup.
Content-Type Use application/json for POST and PUT requests. This is needed to ensure your JSON payload is parsed. Exceptions to this rule include file uploads where application/x-www-form-urlencoded and application/octet-stream should be used instead.

HTTP Headers are used to authorize the acting user via a valid access token, and to describe the type of content being sent, which is typically JSON.

Query Parameters

Parameter Description
phrase If specified will return a partial match on name.

Query Parameters are variables included in the query string portion of the request url, after the ? and they are delimited by &. Be sure to html encode your parameters and values!

JSON Parameters

Parameter Description
name A unique string.

JSON Parameters define the variables to be included in the body of the request. These are typically under the the context of an object, such as "contact".

HTTP Response

The HTTP status 200 OK will be returned when a request is successful and an HTTP Error status will be returned when a request fails.

Most endpoints respond with Content-Type: application/json and a body that contains JSON data.

This is an example of an API response that retrieves a Contact record by ID.

Example

curl "$serverUrl/api/monitoring/contacts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns HTTP 200 and JSON structured like this:

{
  "contact": {
    "id": 1,
    "name": "Morpheus Admin",
    "emailAddress": "admin@morpheusdata.com",
    "smsAddresss": null
  }
}

This is an example of a successful response that contains the specified record.

Error Example

curl "$serverUrl/api/monitoring/contacts/999999" \
  -H "Authorization: BEARER $accessToken"

The above command returns HTTP 404 and JSON structured like this:

{
  "success": false,
  "msg": "Contact not found for this account"
}

This is an example of a 404 error response returned when the specified record was not found.

Errors

When the Morpheus API encounters an error, the response will have an HTTP status of 400 of greater, instead of 200 OK. The error response body contains JSON with information to help troubleshoot the error.

400 Bad Request

curl -XPOST "$serverUrl/api/contacts" \
  -H "Authorization: BEARER $accessToken" \
  -d '{"contact":{"name":"example"}}'

The above command returns HTTP 400 and JSON structured like this:

{
  "success": false,
  "msg": "Unable to save contact",
  "errors": {
    "email": "Please enter a valid email address"
  }
}

This error is returned if your request is invalid. Usually this is because a parameter is missing or the value is invalid. Try modifying your payload and retrying the request.

401 Unauthorized

curl "$serverUrl/api/instances"

The above command returns HTTP 401 and JSON structured like this:

{
  "error": "unauthorized",
  "error_description": "Full authentication is required to access this resource"
}

The unauthorized error will be encountered unless you pass the authorization header.

curl "$serverUrl/api/instances" \
-H "Authorization: BEARER BOGUS_TOKEN"

The above command returns HTTP 401 and JSON structured like this:

{
  "error": "invalid_token",
  "error_description": "Invalid access token: BOGUS_TOKEN"
}

The 401 error code is returned if your access token is invalid or expired.

403 Forbidden

curl "$serverUrl/api/setup" \
  -H "Authorization: BEARER $accessToken"

The above command returns HTTP 403 and JSON structured like this:

{
  "success": false,
  "msg": "You do not have permissions to access this api endpoint"
}

This error is seen if you try to access an endpoint without the required permissions.

For this error example, use the token of user that does not have any admin permissions.

404 Not Found

curl "$serverUrl/api/foobar" \
  -H "Authorization: BEARER $accessToken"

The above command returns HTTP 404 and JSON structured like this:

{
  "success": false,
  "msg": "Unable to find api endpoint GET /api/foobar"
}

This error indicates the specified endpoint path does not exist. Check the URL of your request and try again.

curl "$serverUrl/api/apps/99999" \
  -H "Authorization: BEARER $accessToken"

The above command returns HTTP 404 and JSON structured like this:

{
  "success": false,
  "msg": "App not found"
}

The 404 error code is returned if a resource could be not be found by the specified ID.

500 Internal Server Error

curl "$serverUrl/api/test/500" \
  -H "Authorization: BEARER $accessToken"

The above command returns HTTP 500 and JSON structured like this:

{
  "success": false,
  "msg": "Looks like the server threw a gasket"
}

This error indicates something went wrong with the request and an unexpected error has occured.

This example does not actually work and will return 404 instead. Hopefully you do not encounter a 500 error.

List of Error Codes

The Morpheus API uses the following error codes:

Error Code Description
400 Bad Request – Your request failed. Check your request parameters and try again.
401 Unauthorized – Your API key is invalid. Check your Authorization header.
403 Forbidden – Your API key does not have the required role or permissions.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
406 Not Acceptable – You requested a format that isn’t json.
410 Gone – The entity requested has been removed from our servers.
418 I’m a teapot.
429 Too Many Requests – You’re asking too much of the server. Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Authentication

The Morpheus API uses an OAUTH 2.0 based authentication model.

Authentication is done by passing an access token in the Authorization HTTP header.

Use Get Access Token to acquire a valid access token.

Most /api endpoints require authentication, and will respond with a HTTP 401 without a valid Authorization header.

Authorization Header

This header must be included in all requests that require authorization.

Header Description
Authorization Identifies the Morpheus API access token in the format bearer access_token. Example: Authorization: bearer e1d62c34-f7f5-4713-a874-31491e7707de

Get Access Token

curl -XPOST "$serverUrl/oauth/token?grant_type=password&scope=write&client_id=morph-api" \
  --data-urlencode 'username=admin' --data-urlencode 'password=foobar'

The above command returns JSON structured like this:

{
  "access_token": "e1d62c34-f7f5-4713-a874-31491e7707de",
  "refresh_token": "718cc628-b89f-43f5-bef7-f39887b47e68",
  "token_type": "bearer",
  "expires_in": 30463819,
  "scope": "write"
}

This endpoint provides authentication via username and password of a Morpheus User. The response includes a valid access token. If your current token is expired, a new one will be created and returned.

HTTP Request

POST $serverUrl/oauth/token

HTTP Headers

Header Description
Content-Type application/x-www-form-urlencoded must be passed, this endpoint does not accept application/json

Query Parameters

Parameter Default Description
client_id Client ID, use morph-api. Users may only have one access token per Client ID. The CLI uses morph-cli.
grant_type OAuth Grant Type, use password.
scope OAuth token scope, use write.

Request Parameters

Parameter Default Description
username User username. Subtenant users will need to pass their subdomain prefix like domain\username. The default subdomain is the tenant account ID. Example: 2\neo
password User password

Response

Name Description
access_token The access token for this user (scoped to client_id).
refresh_token The refresh token for this user (scoped to client_id).
expires_in The remaining seconds before the token expires. By default, access tokens are valid for 1 year or until it is refreshed. This time may vary depending on the client_id that is used.
token_type The token type, this will be bearer.
scope The scope, this will be write.

Refresh Access Token

curl -XPOST "$serverUrl/oauth/token?grant_type=refresh_token&client_id=morph-api&scope=write" \
  -d 'refresh_token=718cc628-b89f-43f5-bef7-f39887b47e68'

The above command returns JSON structured like this:

{
  "access_token": "e1d62c34-f7f5-4713-a874-31491e7707de",
  "refresh_token": "718cc628-b89f-43f5-bef7-f39887b47e68",
  "token_type": "bearer",
  "expires_in": 30463819,
  "scope": "write"
}

This endpoint allows refreshing your current access token to get a new token. This is done by passing your current refresh_token. This provides a way to renew your client’s session with the API, and extend the expiration date.

Your refresh_token is returned by Get Access Token.

HTTP Request

POST $serverUrl/oauth/token

HTTP Headers

Header Default Description
Content-Type Use application/x-www-form-urlencoded.

Query Parameters

Parameter Default Description
client_id Client ID, use morph-api. Users only have one access token per Client ID.
grant_type OAuth Grant Type, use refresh_token.
scope OAuth token scope, use write.

Request Body

Parameter Default Description
refresh_token Refresh Token, the current refresh token, scoped to Client ID.

Response

Name Description
access_token The access token for this user, scoped to Client ID.
refresh_token The refresh token for this user, scoped to Client ID.
expires_in The remaining seconds before the token expires. By default, access tokens are valid for 1 year or until it is refreshed.
token_type The token type, this will be bearer.
scope The scope, this will be write.

Whoami

curl "$serverUrl/api/whoami" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "user": {
    "id": 1,
    "accountId": 1,
    "username": "test",
    "displayName": "Test U",
    "email": "testuser@morpheusdata.com",
    "firstName": "Test",
    "lastName": "User",
    "dateCreated": "2016-08-27T19:28:09+0000",
    "lastUpdated": "2020-01-07T05:19:20+0000",
    "enabled": true,
    "accountExpired": false,
    "accountLocked": false,
    "passwordExpired": false,
    "loginCount": 1575,
    "loginAttempts": 0,
    "lastLoginDate": "2020-01-07T05:19:20+0000",
    "roles": [
      {
        "id": 5,
        "authority": "Standard User",
        "description": "A basic user role"
      }
    ],
    "account": {
      "id": 1,
      "name": "root"
    },
    "windowsUsername": "morphtest",
    "linuxUsername": "morphtest"
  },
  "isMasterAccount": true,
  "permissions": [
    {
      "name": "Provisioning: Blueprints",
      "code": "app-templates",
      "access": "full"
    },
    {
      "name": "Provisioning: Apps",
      "code": "apps",
      "access": "full"
    },
    {
      "name": "Logs",
      "code": "logs",
      "access": "full"
    },
    {
      "name": "Monitoring",
      "code": "monitoring",
      "access": "full"
    },
    {
      "name": "Operations: Wiki",
      "code": "operations-wiki",
      "access": "full"
    },
    {
      "name": "Provisioning: Instances",
      "code": "provisioning",
      "access": "full"
    },
    {
      "name": "Operations: Reports",
      "code": "reports",
      "access": "full"
    },
    {
      "name": "Provisioning: Tasks - Script Engines",
      "code": "task-scripts",
      "access": "full"
    },
    {
      "name": "Provisioning: Tasks",
      "code": "tasks",
      "access": "full"
    },
    {
      "name": "Remote Console: Auto Login",
      "code": "terminal-access",
      "access": "yes"
    },
    {
      "name": "Remote Console",
      "code": "terminal",
      "access": "full"
    },
    {
      "name": "Provisioning: Blueprints - Terraform",
      "code": "terraform-template",
      "access": "full"
    },
    {
      "name": "Provisioning: Virtual Images",
      "code": "virtual-images",
      "access": "full"
    }
  ],
  "appliance": {
    "buildVersion": "4.1.2"
  }
}

Provides API to retrieve information about yourself, including your roles and permissions.

The appliance build version is also returned.

HTTP Request

GET $serverUrl/api/whoami

Forgot Password

curl -XPOST "$serverUrl/api/forgot/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "example"
  }'

The above command returns JSON structured like this:

{
  "success": true,
  "msg": "Reset password instructions have been sent to the user 'example', if they exist."
}

This endpoint will trigger the Reset your password email to be sent to the specified user.

The User is identified by username and, if they exist, will be notified via their configured email address. The email notification will indicate a Reset Password Request was made and it will include a token.

Once you obtain the token from the email, it may be used to reset the password of your user.

HTTP Request

POST $serverUrl/api/forgot/send-email

Request Parameters

Parameter Default Description
username Username of the User who would like to reset their password. Subtenant users will need to pass their subdomain prefix like domain\username. The default subdomain is the tenant account ID. Example: 2\neo

Reset Password

curl -XPOST "$serverUrl/api/forgot/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "3d0e0f652f884196b2349756b89f3dfd"
    "password": "WywCx@L5rM5f3W^a"
  }'

The above command returns JSON structured like this:

{
  "success": true,
  "msg": "Password has been updated and account unlocked"
}

This endpoint will reset the password for a user, updating it to the specified value. A secret token must be passed to identify the user who is being updated.

HTTP Request

POST $serverUrl/api/forgot/reset-password

Request Parameters

Parameter Default Description
token The secret Reset Password token that was included in the Forgot Password Email.
password User new password. This is the new password for your user

Operations

The Operations API endpoints provide insight into the Morpheus appliance, activity, reports and approvals. Documentation can be viewed and modified via the Wiki API.

Dashboard

curl "$serverUrl/api/dashboard" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "monitoring": {
    "avgHealth": 8.3333333333,
    "avgResponseTime": 22.3333333333,
    "warningApps": 0,
    "warningChecks": 0,
    "failApps": 0,
    "totalApps": 2,
    "failChecks": 1,
    "successApps": 2,
    "mutedApps": 0,
    "successChecks": 5,
    "totalChecks": 6,
    "mutedChecks": 0,
    "responseTimes": [
      0,
      2,
      2,
      125,
      5,
      0,
      0
    ],
    "allSuccess": false,
    "openIncidents": 0
  },
  "provisioning": {
    "instanceCount": 3,
    "favoriteInstances": [
      {
        "id": 319,
        "accountId": 1,
        "instanceType": {
          "id": 6,
          "code": "apache",
          "category": "web",
          "name": "Apache"
        },
        "zones": [
          {
            "id": 40,
            "accountId": 1,
            "groups": [
              1
            ],
            "name": "qa-azure2",
            "description": null,
            "location": null,
            "visibility": "private",
            "zoneTypeId": 9
          }
        ],
        "layout": {
          "id": 1292,
          "code": "apache-azure-2.4-ubuntu-16.04-single",
          "name": "Azure Apache",
          "description": "This will provision a single process with no redundancy",
          "sortOrder": 10
        },
        "plan": {
          "name": "Basic_A0 (1 Core, 0.75GB Memory) (westus)",
          "id": 187,
          "code": "azure.plan.westus.Basic_A0"
        },
        "name": "test-azureapache1",
        "displayName": "test-azureapache1",
        "description": null,
        "dateCreated": "2019-09-18T16:07:47Z",
        "lastUpdated": "2019-10-25T09:12:29Z",
        "status": "unknown",
        "containerIds": [
          317
        ],
        "containers": [
          {
            "ip": "0.0.0.0",
            "port": {
              "id": 19,
              "exportName": "HTTP",
              "container": {
                "id": 317
              },
              "loadBalancerInstance": null,
              "primaryPort": false,
              "loadBalanceProtocol": null,
              "linkPort": true,
              "internalPort": 80,
              "export": true,
              "portType": {
                "id": 8
              },
              "displayName": "Http",
              "protocol": "http",
              "portIndex": 0,
              "externalIp": null,
              "externalPort": 80,
              "internalIp": null,
              "visible": true,
              "loadBalance": true
            }
          }
        ],
        "version": "2.4",
        "environmentPrefix": null
      }
    ]
  },
  "instanceStats": {
    "usedMemory": 479804000,
    "maxMemory": 1771446368,
    "usedStorage": 6202490880,
    "maxStorage": 55530786816,
    "running": 2,
    "total": 3,
    "totalContainers": 4
  },
  "backups": {
    "accountStats": {
      "totalSizeByDay": [
        0,
        0,
        0,
        0,
        0
      ],
      "totalSizeByDay7Days": [
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "formattedTotalSize": {
        "value": "0",
        "units": "KB"
      },
      "backupCount": 3,
      "totalSize": 0,
      "success": 0,
      "failed": 0,
      "totalCompleted": 0,
      "avgSize": 0,
      "failedRate": 0,
      "successRate": 0,
      "nextFireTotal": 1,
      "backupDayCount": [
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "backupDayCountTotal": 0
    }
  },
  "activity": [
    {
      "success": false,
      "name": "dev-appliance",
      "message": "Check successfully been created.",
      "ts": "2019-10-22T00:06:20Z",
      "activityType": "Monitoring",
      "accountId": 1,
      "userId": 1,
      "userName": "admin",
      "objectId": 238,
      "objectType": "MonitorCheck",
      "_id": "0276e1fc-214d-4cb3-bcf4-9ebda0b26542",
      "timestamp": "2019-10-22T00:06:20Z"
    },
    {
      "success": true,
      "name": "admin",
      "message": "User 'admin' updated. Password changed.",
      "ts": "2019-10-08T21:17:52Z",
      "activityType": "Admin",
      "accountId": 1,
      "userId": 1,
      "userName": "admin",
      "objectId": 96,
      "objectType": "User",
      "_id": "26976fe0-a722-4d20-9849-9405a95d0db9",
      "timestamp": "2019-10-08T21:17:52Z"
    }
  ]
}

This endpoint can be used to view dashboard information about the remote Morpheus appliance. This is an overview and summary of data available to the user that can be used to render a dashboard.

HTTP Request

GET $serverUrl/api/dashboard

Reports

Provides API interfaces for viewing report results and executing new reports.

Get All Report Types

curl "$serverUrl/api/report-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "reportTypes": [
    {
      "id": 21,
      "code": "appCost",
      "name": "Application Cost",
      "category": "cost",
      "dateCreated": "2018-05-02T07:44:46+0000",
      "optionTypes": [
        {
          "id": 1073,
          "name": "endDate",
          "code": "reportType.endDate",
          "description": null,
          "fieldName": "endDate",
          "fieldLabel": "End Date",
          "fieldContext": "report",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "placeHolder": null,
          "helpBlock": "",
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": true,
          "editable": true,
          "creatable": null,
          "config": {
          },
          "displayOrder": 2,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        }
      ]
    },
    {
      "id": 26,
      "code": "workloadSummary",
      "name": "Workload Summary",
      "category": "provisioningInventory",
      "dateCreated": "2018-09-10T08:18:04+0000",
      "optionTypes": [

      ]
    }
  ],
  "meta": {
    "size": 18,
    "total": 18,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all available report types. A report type has optionTypes that define the parameters available when executing a report of that type. The sample response has been abbreviated.

HTTP Request

GET $serverUrl/api/report-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on name
name If specified will return an exact match on name
code If specified will return an exact match on code
category If specified will return an exact match on category

Get All Reports

curl "$serverUrl/api/reports" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "reportResults": [
    {
      "id": 2,
      "type": {
        "id": 21,
        "code": "appCost",
        "name": "Application Cost"
      },
      "reportTitle": "Application Cost Jun 04, 2019 19:28:02",
      "filterTitle": "Jun 04, 2019",
      "status": "ready",
      "dateCreated": "2019-06-04T23:28:02+0000",
      "lastUpdated": "2019-06-04T23:28:02+0000",
      "startDate": null,
      "endDate": null,
      "config": {
        "type": "appCost"
      },
      "createdBy": {
        "id": 1,
        "username": "root"
      }
    },
    {
      "id": 1,
      "type": {
        "id": 6,
        "code": "groupInventory",
        "name": "Group Inventory Summary"
      },
      "reportTitle": "Group Inventory Summary Jul 12, 2019 16:30:04",
      "filterTitle": "Jul 12, 2019 | All Clouds | foo:bar",
      "status": "ready",
      "dateCreated": "2019-07-12T20:30:04+0000",
      "lastUpdated": "2019-07-12T20:30:04+0000",
      "startDate": null,
      "endDate": null,
      "config": {
        "reportType": "groupInventory",
        "cloudId": "",
        "environment": "",
        "tagName": "foo",
        "tagValue": "bar"
      },
      "createdBy": {
        "id": 1,
        "username": "root"
      }
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 25
  }
}

This endpoint returns all reports. This is results of reports that have been executed in the past.

HTTP Request

GET $serverUrl/api/reports

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order, default is dateCreated with direction desc
direction asc Sort direction, use 'desc’ to reverse sort
phrase If specified will return a partial match on name
name If specified will return an exact match on name
reportType If specified will return an exact match on report type code, accepts multiple values
category If specified will return an exact match on report type category, accepts multiple values

Get a Specific Report

curl "$serverUrl/api/reports/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "reportResult": {
    "id": 2,
    "type": {
      "id": 21,
      "code": "appCost",
      "name": "Application Cost"
    },
    "reportTitle": "Application Cost Jun 04, 2019 19:28:02",
    "filterTitle": "Jun 04, 2019",
    "status": "ready",
    "dateCreated": "2019-06-04T23:28:02+0000",
    "lastUpdated": "2019-06-04T23:28:02+0000",
    "startDate": null,
    "endDate": null,
    "config": {
      "type": "appCost"
    },
    "createdBy": {
      "id": 1,
      "username": "root"
    },
    "rows": [
      {
        "id": 536,
        "section": "header",
        "data": "{\"code\":\"totalCount\",\"name\":\"Apps\",\"value\":2",
        "displayOrder": 0
      },
      {
        "id": 535,
        "section": "header",
        "data": "{\"code\":\"totalCost\",\"name\":\"Total Cost\",\"value\":99.99,\"currency\":\"USD\"}",
        "displayOrder": 0
      },
      {
        "id": 534,
        "section": "main",
        "data": "{\"name\":\"testapp1\",\"cost\":0,\"price\":0,\"currency\":\"USD\"}",
        "displayOrder": 0
      },
      {
        "id": 533,
        "section": "main",
        "data": "{\"name\":\"testapp2\",\"cost\":99.99,\"price\":0,\"currency\":\"USD\"}",
        "displayOrder": 1
      }
    ]
  }
}

This endpoint retrieves a specific report result. The response includes the result data as rows which can be used to render the report. Each report type will have sections for data and headers that vary by type, use Download a Specific Report to get the results organized by section.

HTTP Request

GET $serverUrl/api/reports/:id

URL Parameters

Parameter Description
id ID of the report result

Download a Specific Report

curl "$serverUrl/api/reports/download/3" \
  -H "Authorization: BEARER $accessToken"

The above command returns Content-Type: "application/octet-stream" and Content-disposition: attachment;filename=reportTitle.json. The body contains JSON structured like this:

{
  "data": [
    {
      "name": "dev-amazon",
      "cost": 7.199999999999999,
      "price": 7.199999999999999,
      "currency": "USD",
      "deleted": false,
      "hostCount": 0,
      "instanceCount": 2,
      "discoveredCount": 2
    },
    {
      "name": "dev-azure",
      "cost": 4775.508356680239,
      "price": 4775.508356680239,
      "currency": "USD",
      "deleted": false,
      "hostCount": 126,
      "instanceCount": 0,
      "discoveredCount": 1
    },
  ],
  "headers": [
    {
      "code": "totalCost",
      "name": "Total Cost",
      "value": 4782.7083566802385,
      "displayOrder": 4,
      "currency": "USD"
    },
    {
      "code": "instanceCount",
      "name": "Instances",
      "value": 5,
      "displayOrder": 2
    },
    {
      "code": "count",
      "name": "Clouds",
      "value": 2,
      "displayOrder": 0
    },
    {
      "code": "discoveredCount",
      "name": "Discovered VMs",
      "value": 13,
      "displayOrder": 3
    },
    {
      "code": "hostCount",
      "name": "Nodes",
      "value": 127,
      "displayOrder": 2
    }
  ],
  "footers": [

  ],
  "reportType": "Cloud Cost",
  "reportTypeId": 5,
  "resultId": 146,
  "reportDate": "2021-08-26T16:59:45Z",
  "createdBy": "admin",
  "createdById": 1
}

This endpoint downloads a specific report result as a file attachment. The default file format is json.

HTTP Request

GET $serverUrl/api/reports/download/:id(.:format)

URL Parameters

Parameter Description
id ID of the report result
format Format of the rendered report file, json or csv. The default is .json.

Run a Report

curl -XPOST "$serverUrl/api/reports" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "type": "appCost",
    "startDate": "2019-01-01",
    "endDate": "2020-01-01"
  }}'

The above command returns JSON structured like getting a single report:

This endpoint execute the specified report type and create a new report result.

HTTP Request

POST $serverUrl/api/reports

JSON Report Parameters

Parameter Default Description
type The Report Type code to be executed.

The available parameters vary by report type. Refer to the defined optionTypes for each report.

JSON Common Report Parameters

Parameter Default Description
startDate The start date for the report
endDate The end date for the report
groupId The Group ID filter for the report
cloudId The Cloud ID filter for the report

Delete a Report

curl -XDELETE "$serverUrl/api/reports/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint will delete a report result.

HTTP Request

DELETE $serverUrl/api/reports/:id

URL Parameters

Parameter Description
ID The ID of the report result.

Wiki

Morpheus provides a way to create and edit documentation in the form of wiki pages. Wiki pages use the markdown format and can be categorized to group them with other pages. Instances, apps, servers, clouds and groups can have their own wiki page associated to them.

Get All Wiki Pages

curl "$serverUrl/api/wiki/pages"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "pages": [
    {
      "id": 1,
      "name": "Home",
      "urlName": "home",
      "category": null,
      "refId": null,
      "refType": null,
      "format": "markdown",
      "content": "Welcome to the home page for this Morpheus wiki.",
      "createdBy": {
        "id": 1,
        "username": "admin"
      },
      "updatedBy": {
        "id": 1,
        "username": "admin"
      },
      "dateCreated": "2019-06-27T16:55:59+0000",
      "lastUpdated": "2019-06-27T16:55:59+0000"
    },
    {
      "id": 2,
      "name": "README",
      "urlName": "info/readme",
      "category": "info",
      "refId": null,
      "refType": null,
      "format": "markdown",
      "content": "A readme file for this local dev appliance.\nNeat.",
      "createdBy": {
        "id": 1,
        "username": "admin"
      },
      "updatedBy": {
        "id": 1,
        "username": "admin"
      },
      "dateCreated": "2019-06-27T14:44:22+0000",
      "lastUpdated": "2019-06-27T14:44:22+0000"
    },
    {
      "id": 3,
      "name": "My Group",
      "urlName": "my-group",
      "category": "groups",
      "refId": 1,
      "refType": "ComputeSite",
      "format": "markdown",
      "content": "#My Group\nThis is a test group",
      "createdBy": {
        "id": 1,
        "username": "admin"
      },
      "updatedBy": {
        "id": 1,
        "username": "admin"
      },
      "dateCreated": "2019-06-28T01:41:45+0000",
      "lastUpdated": "2019-06-28T01:41:45+0000"
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves wiki pages associated with the account.

HTTP Request

GET $serverUrl/api/wiki/pages

Query Parameters

Parameter Default Description
name If specified will return an exact match on name or urlName
phrase If specified will return a partial match on name

Get All Wiki Categories

curl "$serverUrl/api/wiki/categories"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "categories": [
    {
      "name": "apps",
      "pageCount": 1
    },
    {
      "name": "clouds",
      "pageCount": 1
    },
    {
      "name": "groups",
      "pageCount": 1
    },
    {
      "name": "info",
      "pageCount": 1
    },
    {
      "name": "instances",
      "pageCount": 2
    },
    {
      "name": "servers",
      "pageCount": 2
    }
  ]
}

This endpoint retrieves all categories associated with the account. The results are not paginated. The categories returned are those of the found pages.

HTTP Request

GET $serverUrl/api/wiki/categories

Query Parameters

Parameter Default Description
phrase If specified will return a partial match on category name
pagePhrase If specified will return a partial match on page name

Get a Specific Wiki Page

curl "$serverUrl/api/wiki/pages/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:


{
  "page": {
      "id": 1,
      "name": "Home",
      "urlName": "home",
      "category": null,
      "refId": null,
      "refType": null,
      "format": "markdown",
      "content": "The home page for this wiki.",
      "createdBy": {
        "id": 1,
        "username": "admin"
      },
      "updatedBy": {
        "id": 1,
        "username": "admin"
      },
      "dateCreated": "2019-06-27T16:55:59+0000",
      "lastUpdated": "2019-06-27T16:55:59+0000"
    }
}

This endpoint retrieves a specific wiki page.

HTTP Request

GET $serverUrl/api/wiki/pages/:id

URL Parameters

Parameter Description
ID The ID of the Wiki Page

Create a Wiki Page

curl -XPOST "$serverUrl/api/wiki/pages" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "name": "Sample Doc",
    "category": "info",
    "content": "#Sample Doc\nA sample document in **markdown**."
  }}'

The above command returns JSON structured like getting a single wiki page:

HTTP Request

POST $serverUrl/api/wiki/pages

JSON Page Parameters

Parameter Default Description
name A unique name scoped to your account for the wiki page.
category Optional category for grouping with other pages.
content The content of the page (markdown).

Update a Wiki Page

curl -XPUT "$serverUrl/api/wiki/pages/4" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "#Sample Doc\nAn updated sample document in **markdown**.\nCheers!"
  }}'

The above command returns JSON structured like getting a single wiki page

HTTP Request

PUT $serverUrl/api/wiki/pages/:id

URL Parameters

Parameter Description
ID The ID of the Wiki Page

JSON Page Parameters

Parameter Default Description
name A unique name scoped to your account for the wiki page.
category Optional category for grouping with other pages.
content The content of the page (markdown).

Delete a Wiki Page

curl -XDELETE "$serverUrl/api/wiki/pages/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page

Will delete a Wiki Page from the system.

HTTP Request

DELETE $serverUrl/api/wiki/pages/:id

URL Parameters

Parameter Description
ID The ID of the Wiki Page

The above command returns JSON structure like this:

{
  "success": true
}

Get a Wiki Page For Instance

curl "$serverUrl/api/instances/1/wiki" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page.

This endpoint retrieves the wiki page for an instance. If its page does not yet exist, the response is still 200 OK with a body like “page”:null.

HTTP Request

GET $serverUrl/api/instances/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Instance

Update a Wiki Page For Instance

curl -XPUT "$serverUrl/instances/1/wiki" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "Lots of good information about this instance."
  }}'

The above command returns JSON structured like getting a single wiki page:

This endpoint updates the wiki page for an instance. The page will be created if it does not yet exist.

HTTP Request

PUT $serverUrl/api/instances/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Instance

JSON Page Parameters

Parameter Default Description
name (instance name) A unique name scoped to your account for the wiki page.
content The content of the page (markdown).

Get a Wiki Page For App

curl "$serverUrl/api/apps/1/wiki" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page.

This endpoint retrieves the wiki page for an app. If its page does not yet exist, the response is still 200 OK with a body like “page”:null.

HTTP Request

GET $serverUrl/api/apps/:id/wiki

URL Parameters

Parameter Description
ID The ID of the App

Update a Wiki Page For App

curl -XPUT "$serverUrl/apps/1/wiki" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "Lots of good information about this app."
  }}'

The above command returns JSON structured like getting a single wiki page:

This endpoint updates the wiki page for an app. The page will be created if it does not yet exist.

HTTP Request

PUT $serverUrl/api/apps/:id/wiki

URL Parameters

Parameter Description
ID The ID of the App

JSON Page Parameters

Parameter Default Description
name (app name) A unique name scoped to your account for the wiki page.
content The content of the page (markdown).

Get a Wiki Page For Cluster

curl "$serverUrl/api/clusters/1/wiki" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page.

This endpoint retrieves the wiki page for a cluster. If its page does not yet exist, the response is still 200 OK with a body like “page”:null.

HTTP Request

GET $serverUrl/api/clusters/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Cluster

Update a Wiki Page For Cluster

curl -XPUT "$serverUrl/clusters/1/wiki" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "Lots of good information about this cluster."
  }}'

The above command returns JSON structured like getting a single wiki page:

This endpoint updates the wiki page for a cluster. The page will be created if it does not yet exist.

HTTP Request

PUT $serverUrl/api/clusters/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Cluster

JSON Page Parameters

Parameter Default Description
name (cluster name) A unique name scoped to your account for the wiki page.
content The content of the page (markdown).

Get a Wiki Page For Server

curl "$serverUrl/api/servers/1/wiki" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page.

This endpoint retrieves the wiki page for a server. If its page does not yet exist, the response is still 200 OK with a body like “page”:null.

HTTP Request

GET $serverUrl/api/servers/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Server

Update a Wiki Page For Server

curl -XPUT "$serverUrl/servers/1/wiki" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "Lots of good information about this server."
  }}'

The above command returns JSON structured like getting a single wiki page:

This endpoint updates the wiki page for a server. The page will be created if it does not yet exist.

HTTP Request

PUT $serverUrl/api/servers/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Server

JSON Page Parameters

Parameter Default Description
name (server name) A unique name scoped to your account for the wiki page.
content The content of the page (markdown).

Get a Wiki Page For Cloud

curl "$serverUrl/api/zones/1/wiki" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page.

This endpoint retrieves the wiki page for a cloud. If its page does not yet exist, the response is still 200 OK with a body like “page”:null.

HTTP Request

GET $serverUrl/api/zones/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Cloud

Update a Wiki Page For Cloud

curl -XPUT "$serverUrl/zones/1/wiki" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "Lots of good information about this cloud."
  }}'

The above command returns JSON structured like getting a single wiki page:

This endpoint updates wiki page for a cloud. The page will be created if it does not yet exist.

HTTP Request

PUT $serverUrl/api/zones/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Cloud

JSON Page Parameters

Parameter Default Description
name (cloud name) A unique name scoped to your account for the wiki page.
content The content of the page (markdown).

Get a Wiki Page For Group

curl "$serverUrl/api/groups/1/wiki" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single wiki page.

This endpoint retrieves the wiki page for a group. If its page does not yet exist, the response is still 200 OK with a body like “page”:null.

HTTP Request

GET $serverUrl/api/groups/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Group

Update a Wiki Page For Group

curl -XPUT "$serverUrl/groups/1/wiki" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"page":{
    "content": "Lots of good information about this group."
  }}'

The above command returns JSON structured like getting a single wiki page:

This endpoint updates the wiki page for a group. The page will be created if it does not yet exist.

HTTP Request

PUT $serverUrl/api/groups/:id/wiki

URL Parameters

Parameter Description
ID The ID of the Group

JSON Page Parameters

Parameter Default Description
name (group name) A unique name scoped to your account for the wiki page.
content The content of the page (markdown).

Budgets

Provides API interfaces for managing budgets.

Get All Budgets

curl "$serverUrl/api/budgets" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "budgets": [
     {
      "id": 1,
      "name": "sample budget",
      "description": "a yearly budget",
      "account": {
        "id": 1,
        "name": "root"
      },
      "refScope": "account",
      "refType": null,
      "refId": null,
      "refName": "root",
      "interval": "year",
      "period": "year",
      "year": "2020",
      "resourceType": "all",
      "timezone": "America/New_York",
      "startDate": "2020-01-01T05:00:00+0000",
      "endDate": "2021-01-01T04:59:59+0000",
      "active": true,
      "enabled": true,
      "rollover": false,
      "costs": [
        1000.0
      ],
      "averageCost": 83.33333333333333,
      "totalCost": 1000.0,
      "currency": "USD",
      "warningLimit": null,
      "overLimit": null,
      "externalId": null,
      "internalId": null,
      "createdById": 1,
      "createdByName": "Admin",
      "updatedById": null,
      "updatedByName": null,
      "dateCreated": "2020-01-03T17:40:08+0000",
      "lastUpdated": "2020-01-03T17:40:08+0000"
    },
    {
      "id": 2,
      "name": "my budget",
      "description": "99 per month",
      "account": {
        "id": 1,
        "name": "root"
      },
      "refScope": "account",
      "refType": null,
      "refId": null,
      "refName": "root",
      "interval": "month",
      "period": "year",
      "year": "2020",
      "resourceType": "all",
      "timezone": "America/New_York",
      "startDate": "2020-01-01T05:00:00+0000",
      "endDate": "2021-01-01T04:59:59+0000",
      "active": true,
      "enabled": true,
      "rollover": false,
      "costs": [
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
        99.0,
      ],
      "averageCost": 99.0,
      "totalCost": 1188.0,
      "currency": "USD",
      "warningLimit": null,
      "overLimit": null,
      "externalId": null,
      "internalId": null,
      "createdById": 1,
      "createdByName": "Admin",
      "updatedById": null,
      "updatedByName": null,
      "dateCreated": "2020-01-03T17:37:51+0000",
      "lastUpdated": "2020-01-03T17:37:51+0000"
    },
    {
      "id": 3,
      "name": "quarters",
      "description": "Quarterly budget for tenant Acme",
      "account": {
        "id": 1,
        "name": "root"
      },
      "refScope": "tenant",
      "refType": "Account",
      "refId": 47,
      "refName": "Acme",
      "interval": "quarter",
      "period": "year",
      "year": "2020",
      "resourceType": "all",
      "timezone": "America/New_York",
      "startDate": "2020-01-01T05:00:00+0000",
      "endDate": "2021-01-01T04:59:59+0000",
      "active": true,
      "enabled": true,
      "rollover": false,
      "costs": [
        250.0,
        250.0,
        250.0,
        500.0,
      ],
      "averageCost": 312.5,
      "totalCost": 1250.0,
      "currency": "USD",
      "warningLimit": null,
      "overLimit": null,
      "externalId": null,
      "internalId": null,
      "createdById": 1,
      "createdByName": "James D",
      "updatedById": null,
      "updatedByName": null,
      "dateCreated": "2020-01-02T02:54:34+0000",
      "lastUpdated": "2020-01-03T17:43:52+0000"
    }
  ],
  "meta": {
    "size": 3,
    "total": 3,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all budgets.

HTTP Request

GET $serverUrl/api/budgets

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by matching name
name Filter by name

Get a Specific Budget

curl "$serverUrl/api/budgets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "budget": {
    "id": 1,
    "name": "sample budget",
    "description": "a yearly budget",
    "account": {
      "id": 1,
      "name": "root"
    },
    "refScope": "account",
    "refType": null,
    "refId": null,
    "refName": "root",
    "interval": "year",
    "period": "year",
    "year": "2020",
    "resourceType": "all",
    "timezone": "America/New_York",
    "startDate": "2020-01-01T05:00:00+0000",
    "endDate": "2021-01-01T04:59:59+0000",
    "active": true,
    "enabled": true,
    "rollover": false,
    "costs": [
      1000.0
    ],
    "averageCost": 83.33333333333333,
    "totalCost": 1000.0,
    "currency": "USD",
    "warningLimit": null,
    "overLimit": null,
    "externalId": null,
    "internalId": null,
    "createdById": 1,
    "createdByName": "Admin",
    "updatedById": null,
    "updatedByName": null,
    "dateCreated": "2020-01-03T17:40:08+0000",
    "lastUpdated": "2020-01-03T17:40:08+0000",
    "stats": {
      "averageCost": 83.33,
      "totalCost": 1000.0,
      "currency": "USD",
      "conversionRate": 1,
      "intervals": [
        {
          "index": 0,
          "year": "Y1",
          "shortYear": "Y1",
          "budget": 1000.0,
          "cost": 15.1016
        }
      ],
      "current": {
        "estimatedCost": 15.1,
        "lastCost": 15.1
      }
    }
  }
}

This endpoint will retrieve a specific budget by id.

HTTP Request

GET $serverUrl/api/budgets/:id

URL Parameters

Parameter Description
ID The ID of the budget

Create a Budget

curl -XPOST "$serverUrl/api/budgets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"budget":{
    "name": "sample budget",
    "year": "2020",
    "interval": "year",
    "scope": "account",
    "costs": [1000]
  }}'

The above command returns JSON structured like getting a single budget:

This endpoint creates a new budget.

HTTP Request

POST $serverUrl/api/budgets

JSON Parameters

The following parameters are passed inside an object named budget.

Parameter Default Description
name A unique name for the budget
description A description of the budget
period year Budget period, year
year 2020 Budget period value, default is the current year. This can also be passed as custom along with a startDate and endDate.
startDate Start Date for custom period budgets, should be the first of a month. eg. 2021-01-01
endDate End Date for custom period budgets, should be the last day of a month, and must be 12, 24, or 36 months after the start date. eg. 2021-12-31
interval year Budget interval, year, quarter, month.
scope The type of the scope for the budget, account, group, cloud, user. The default scope is account, which means the entire account.
scopeTenantId The Tenant ID to scope to, for use with "scope"=tenant.
scopeGroupId The Group ID to scope to, for use with "scope"=group.
scopeCloudId The Cloud ID to scope to, for use with "scope"=cloud.
scopeUserId The User ID to scope to, for use with "scope"=user.
costs Array of budget cost amounts that varies in length by interval. For interval year use [1000]. For interval quarter use [200,200,200,400]. For interval month use [99,99,99,99,99,99,99,99,99,99,99,299] (other 10 months omitted). Custom budgets of more than one year may have more cost values. When creating a new schedule, the default cost for a given interval is 0 so be sure to specify a cost for every interval when creating a new budget.

Updating a Budget

curl -XPUT "$serverUrl/api/budgets/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"budget":{
    "interval": "quarter",
    "costs": [1000,1000,1000,2000]
  }}'

The above command returns JSON structured like getting a single budget:

This endpoint updates a budget.

HTTP Request

PUT $serverUrl/api/budgets/:id

URL Parameters

Parameter Description
ID The ID of the budget

JSON Parameters

The following parameters are passed inside an object named budget.

Parameter Default Description
name A unique name for the budget
description A description of the budget
period year Budget period, year
year 2020 Budget period value, default is the current year. This can also be passed as custom along with a startDate and endDate.
startDate Start Date for custom period budgets, should be the first of a month. eg. 2021-01-01
endDate End Date for custom period budgets, should be the last day of a month, and must be exactly 12, 24, or 36 months after the start date. eg. 2021-12-31
interval year Budget interval, year, quarter, month.
scope The type of the scope for the budget, account, group, cloud, user. The default scope is account, which means the entire account.
scopeTenantId The Tenant ID to scope to, for use with "scope"=tenant.
scopeGroupId The Group ID to scope to, for use with "scope"=group.
scopeCloudId The Cloud ID to scope to, for use with "scope"=cloud.
scopeUserId The User ID to scope to, for use with "scope"=user.
costs Array of budget cost amounts that varies in length by interval. For interval year use [1000]. For interval quarter use [200,200,200,400]. For interval month use [99,99,99,99,99,99,99,99,99,99,99,299] (other 10 months omitted). Custom budgets of more than one year may have more cost values. When creating a new schedule, the default cost for a given interval is 0 so be sure to specify a cost for every interval when creating a new budget.

Delete a Budget

curl -XDELETE "$serverUrl/api/budgets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint deletes a budget from the system.

HTTP Request

DELETE $serverUrl/api/budgets/:id

URL Parameters

Parameter Description
ID The ID of the budget

Approvals

Provides API interfaces for managing approvals within Morpheus.

Get All Approvals

curl "$serverUrl/api/approvals" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "approvals": [
    {
      "id": 3,
      "name": "APPROVAL-0000003",
      "internalId": null,
      "externalId": null,
      "externalName": null,
      "requestType": "Instance Approval",
      "account": {
        "id": 1,
        "name": "Stubby Toes Inc."
      },
      "approver": {
        "id": 1,
        "name": "Stubby Toes Inc."
      },
      "accountIntegration": null,
      "status": "1 approved",
      "errorMessage": null,
      "dateCreated": "2019-11-07T02:35:15+0000",
      "lastUpdated": "2019-11-07T02:35:15+0000",
      "requestBy": "Stubby Toes"
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "max": 25,
    "offset": 0
  }
}    

This endpoint retrieves all approvals.

HTTP Request

GET $serverUrl/api/approvals

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, externalName and requestBy filter, restricts query to only load approvals which contain the phrase specified
name Name filter, restricts query to only load approval matching name specified

Get a Specific Approval

curl "$serverUrl/api/approvals/3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "approval": {
    "id": 3,
    "name": "APPROVAL-0000003",
    "internalId": null,
    "externalId": null,
    "externalName": null,
    "requestType": "Instance Approval",
    "account": {
      "id": 1,
      "name": "Stubby Toes Inc."
    },
    "approver": {
      "id": 1,
      "name": "Stubby Toes Inc."
    },
    "accountIntegration": null,
    "status": "1 cancelled",
    "errorMessage": null,
    "dateCreated": "2019-11-07T02:35:15+0000",
    "lastUpdated": "2019-11-07T02:35:15+0000",
    "requestBy": "Stubby Toes",
    "approvalItems": [
      {
        "id": 3,
        "name": null,
        "externalId": null,
        "externalName": null,
        "internalId": null,
        "approvedBy": "Stubby Toes",
        "deniedBy": "Stubby Toes",
        "status": "cancelled",
        "errorMessage": null,
        "dateCreated": "2019-11-07T02:35:15+0000",
        "lastUpdated": "2019-11-18T21:00:25+0000",
        "dateApproved": "2019-11-18T19:56:30+0000",
        "dateDenied": null,
        "approval": {
          "id": 3
        },
        "reference": {
          "id": 3,
          "type": "instance",
          "name": "dans-ubuntu-3",
          "displayName": "dans-ubuntu-3"
        }
      }
    ]
  }
}

This endpoint retrieves a specific approval.

HTTP Request

GET $serverUrl/api/approvals/:id

URL Parameters

Parameter Description
id ID of the approval

Get a Specific Approval Item

curl "$serverUrl/api/approval-items/3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "approvalItem": {
    "id": 3,
    "name": null,
    "externalId": null,
    "externalName": null,
    "internalId": null,
    "approvedBy": "Stubby Toes",
    "deniedBy": "Stubby Toes",
    "status": "cancelled",
    "errorMessage": null,
    "dateCreated": "2019-11-07T02:35:15+0000",
    "lastUpdated": "2019-11-18T21:00:25+0000",
    "dateApproved": "2019-11-18T19:56:30+0000",
    "dateDenied": null,
    "approval": {
      "id": 3
    },
    "reference": {
      "id": 3,
      "type": "instance",
      "name": "dans-ubuntu-3",
      "displayName": "dans-ubuntu-3"
    }
  }
}

This endpoint retrieves a specific approval item

HTTP Request

GET $serverUrl/api/approval-items/:id

URL Parameters

Parameter Description
id ID of the approval item

Update an Approval Item

curl -XPUT "$serverUrl/api/approval-items/3/approve" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint updates a specific approval item based upon specified action

HTTP Request

PUT $serverUrl/api/approval-items/:id/:action

URL Parameters

Parameter Required Description
id Y ID of the approval item
action Y Approval item action [approve, deny, cancel]

Activity

This endpoint provides data about activity with the Morpheus appliance. User activity and other Morpheus events can be seen here.

The most recent activity is returned by default.

Get All Activity

curl "$serverUrl/api/activity" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "activity": [
    {
      "_id": "ed970f86-c2bd-4ea2-8c3e-37494c8d8c67",
      "success": false,
      "activityType": "Alert",
      "name": "test check",
      "message": "Check has successfully been deleted",
      "objectId": 239,
      "objectType": "MonitorCheck",
      "user": {
        "id": 22,
        "username": "tester"
      },
      "timestamp": "2019-10-23T19:31:54Z"
    },
    {
      "_id": "247f122a-2dd6-4d92-a945-9e1fc35d8e51",
      "success": false,
      "activityType": "Monitoring",
      "name": "dev-appliance",
      "message": "Check has successfully been updated.",
      "objectId": 238,
      "objectType": "MonitorCheck",
      "user": {
        "id": 1,
        "username": "root"
      },
      "ts": "2019-10-22T07:55:49Z"
    },
    {
      "_id": "0276e1fc-214d-4cb3-bcf4-9ebda0b26542",
      "success": false,
      "activityType": "Monitoring",
      "name": "dev-appliance",
      "message": "Check successfully been created.",
      "objectId": 238,
      "objectType": "MonitorCheck",
      "user": {
        "id": 1,
        "username": "root"
      },
      "ts": "2019-10-22T00:06:20Z"
    },
    {
      "_id": "26976fe0-a722-4d20-9849-9405a95d0db9",
      "success": true,
      "activityType": "Admin",
      "name": "julius",
      "message": "User 'julius' updated. Password changed.",
      "objectId": 96,
      "objectType": "User",
      "user": {
        "id": 1,
        "username": "root"
      },
      "ts": "2019-10-08T21:17:52Z"
    }
  ]
}

HTTP Request

GET $serverUrl/api/activity

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use ‘desc’ to reverse sort
name Filter by name
phrase Filter by wildcard search of name and description
userId Filter by User ID.
tenantId Filter by Tenant ID. Only available to the master account.
timeframe month Filter by a timeframe. eg. today,yesterday,week,month,3months.
start (1 month ago) Filter by activity on or after a date(time)
end (current time) Filter by activity on or before a date(time)

Usage

Provides endpoints for viewing a list of usage for all your Containers and Servers. Morpheus keeps track of resource usage as the time periods that a resource was in use. A new usage record is created every time a resource is started or stopped. Each usage record includes the applied pricing and accumulated charges during the interval. Price is based on the assigned service plan.

This endpoint outputs usage data in the same format as the Billing api.

List Usages

curl "$serverUrl/api/usage"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "usages": [
    {
      "id": 28791,
      "zoneName": "aws",
      "name": "example",
      "planName": "Amazon T2 Nano - 1 Core, 0.5GB Memory",
      "startDate": "2020-10-26T16:48:54Z",
      "endDate": "2020-10-26T17:00:37Z",
      "status": "running",
      "price": 0.001668677955115256,
      "costDetails": {
        "refType": "container",
        "refUUID": "9287ee06-75c6-4772-840c-fab7b2d668bd",
        "refId": 938,
        "startDate": "2020-10-26T16:48:54Z",
        "endDate": "2020-10-26T17:00:37Z",
        "cost": 0.001668677955115256,
        "price": 0.001668677955115256,
        "numUnits": 0.195410555555,
        "unit": "hour",
        "currency": "USD",
        "usages": [
          {
            "cost": 0.001668677955115256,
            "price": 0.001668677955115256,
            "createdByUser": "Test User",
            "createdByUserId": 127,
            "siteId": 1,
            "siteName": "mygroup",
            "siteUUID": "9a18a409-e3b7-438b-b3d8-e393652f7c60",
            "siteCode": null,
            "currency": "USD",
            "startDate": "2020-10-26T16:48:54Z",
            "endDate": "2020-10-26T17:00:37Z",
            "status": "running",
            "tags": [],
            "applicablePrices": [
              {
                "startDate": "2020-10-26T16:48:54Z",
                "endDate": "2020-10-26T17:00:37Z",
                "numUnits": 0.195410555555,
                "cost": 0.001668677955115256,
                "price": 0.001668677955115256,
                "currency": "USD",
                "prices": [
                  {
                    "type": "compute",
                    "pricePerUnit": 0.0069,
                    "costPerUnit": 0.0069,
                    "cost": 0.0013483328333295,
                    "price": 0.0013483328333295,
                    "quantity": null
                  },
                  {
                    "type": "storage",
                    "pricePerUnit": 0.000163934424,
                    "costPerUnit": 0.000163934424,
                    "cost": 3.203451686842893e-05,
                    "price": 3.203451686842893e-05,
                    "quantity": 10
                  }
                ]
              }
            ],
            "servicePlanId": 1,
            "servicePlanName": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
          }
        ],
        "numUsages": 1,
        "totalUsages": 1,
        "hasMoreUsages": false,
        "foundPricing": true
      }
    }
  ],
  "meta": {
    "size": 25,
    "total": 28133,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves a paginated list of usage records. The usages are scoped to only include resources you have access to.

HTTP Request

GET $serverUrl/api/usage

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort startDate desc Sort order, default is startDate desc
direction asc Sort direction: asc or desc
phrase Filter by wildcard search of resource name
type Filter by a specific resource type: container, server, discoveredServer or loadBalancer
startDate Filter by startDate greater than or equal to a specified date
endDate Filter by endDate less than or equal to a specified date

Billing

Provides API interfaces for viewing billing usage information by tenant, zone, instance or server. By default, usage is returned is from the beginning of the current month until now. The date range is parameterized but the end date cannot exceed the current date.

Billing By Tenant

curl "$serverUrl/api/billing/account" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "accountId": 1,
    "accountUUID": "775333da-8487-11ec-a8a3-0242ac120002",
    "name": "Morpheus Data",
    "startDate": "2017-02-01T07:00:00Z",
    "endDate": "2017-02-22T23:03:13Z",
    "priceUnit": "hour",
    "price": 0,
    "cost": 0,
    "zones": [
          {
                "computeServers": [
                    {
                        "servers": [
                          {
                            "usages": [
                              ]
                            }
                        ]
                    }
                ],
                "instances": [
                  {
                    "instances": [
                        {
                              "containers": {
                                "usages": [
                                  ]
                              }
                          }
                      ]
                    }
                ]
            }
        ]
  }
}

Retrieves billing information for the requesting user’s account.

HTTP Request

GET $serverUrl/api/billing/account

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeComputeServers true Optional ability to exclude compute servers
includeInstances true Optional ability to exclude instances
includeDiscoveredServers true Optional ability to exclude discovered servers
includeLoadBalancers true Optional ability to exclude load balancers
includeVirtualImages true Optional ability to exclude virtual images
includeSnapshots true Optional ability to exclude snapshots

Billing For a Specific Tenant

Will retrieve billing information for a specific tenant, if it is the current account or a sub account of the requesting user’s account.

curl "$serverUrl/api/billing/account/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "accountId": 1,
    "accountUUID": "775333da-8487-11ec-a8a3-0242ac120002",
    "name": "Morpheus Data",
    "startDate": "2017-02-01T07:00:00Z",
    "endDate": "2017-02-22T23:03:13Z",
    "priceUnit": "hour",
    "price": 0,
    "cost": 0,
    "zones": [
      {
        "computeServers": [
          {
            "servers": [
              {
                "usages": [
                ]
              }
            ]
          }
        ],
        "instances": [
          {
            "instances": [
              {
                "containers": {
                  "usages": [
                                  ]
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

This endpoint will retrieve a specific account by id if the user has permission to access it.

HTTP Request

GET $serverUrl/api/billing/account/:id

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeComputeServers true Optional ability to exclude compute servers
includeInstances true Optional ability to exclude instances
includeDiscoveredServers true Optional ability to exclude discovered servers
includeLoadBalancers true Optional ability to exclude load balancers
includeVirtualImages true Optional ability to exclude virtual images
includeSnapshots true Optional ability to exclude snapshots

Billing For All Zones

curl "$serverUrl/api/billing/zones" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "startDate": "2017-02-01T07:00:00Z",
    "endDate": "2017-02-22T23:03:13Z",
    "priceUnit": "hour",
    "price": 0,
    "cost": 0,
    "zones": [
      {
        "computeServers": [
          {
            "servers": [
              {
                "usages": [
                ]
              }
            ]
          }
        ],
        "instances": [
          {
            "instances": [
              {
                "containers": {
                  "usages": [
                  ]
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Retrieves billing information for all zones on the requestor’s account.

HTTP Request

GET $serverUrl/api/billing/zones

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeTenants false Optional ability to include all subtenant billing information when calling from a master tenant user
accountId Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with “includeTenants=true” accountId is ignored
includeComputeServers true Optional ability to exclude compute servers
includeInstances true Optional ability to exclude instances
includeDiscoveredServers true Optional ability to exclude discovered servers
includeLoadBalancers true Optional ability to exclude load balancers
includeVirtualImages true Optional ability to exclude virtual images
includeSnapshots true Optional ability to exclude snapshots

Billing For a Specific Zone

curl "$serverUrl/api/billing/zones/0801f6cd-4423-489f-859f-ee6ce24fd2ef" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "zoneName": "",
    "zoneId": 1,
    "zoneUUID": "0801f6cd-4423-489f-859f-ee6ce24fd2ef",
    "startDate": "2017-01-01T00:00:00Z",
    "endDate": "2017-01-31T23:59:59Z",
    "priceUnit": "hour",
    "computeServers": {
      "servers": [
        {
          "usages": [
          ]
        }
      ]
    },
    "instances": {
      "instances": [
        {
          "containers": [
            {
              "usages": [
                {
                  "applicablePrices": [
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Retrieves billing information for a specific zone in the requestor’s account. Use zoneUUID whenever possible.

HTTP Request

GET $serverUrl/api/billing/zones/:zoneUUID|:id

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeTenants false Optional ability to include all subtenant billing information when calling from a master tenant user
accountId Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with “includeTenants=true” accountId is ignored
includeComputeServers true Optional ability to exclude compute servers
includeInstances true Optional ability to exclude instances
includeDiscoveredServers true Optional ability to exclude discovered servers
includeLoadBalancers true Optional ability to exclude load balancers
includeVirtualImages true Optional ability to exclude virtual images
includeSnapshots true Optional ability to exclude snapshots

Billing For All Servers

curl "$serverUrl/api/billing/servers" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "price": 0,
    "cost": 0,
    "startDate": "2017-03-01T07:00:00Z",
    "endDate": "2017-03-09T22:03:28Z",
    "servers": [
      {
        "refType": "computeServer",
        "refUUID": "dca94ff0-2d5d-4e1e-985c-253e498140bf",
        "refId": 1,
        "startDate": "2017-01-01T00:00:00Z",
        "endDate": "2017-01-31T23:59:59Z",
        "cost": 0,
        "price": 0,
        "usages": [
        ],
        "numUnits": 0,
        "unit": "hour",
        "name": "name"
      }
    ]
  }
}

Retrieves billing information for all servers (container hosts) on the requestor’s account.

HTTP Request

GET $serverUrl/api/billing/servers

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeTenants false Optional ability to include all subtenant billing information when calling from a master tenant user
accountId Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with “includeTenants=true” accountId is ignored

Billing For a Specific Server

curl "$serverUrl/api/billing/servers/dca94ff0-2d5d-4e1e-985c-253e498140bf" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "refType": "computeServer",
    "refUUID": "dca94ff0-2d5d-4e1e-985c-253e498140bf",
    "refId": 1,
    "startDate": "2017-01-01T00:00:00Z",
    "endDate": "2017-01-31T23:59:59Z",
    "cost": 0,
    "price": 0,
    "usages": [
    ],
    "numUnits": 0,
    "unit": "hour",
    "name": "name"
  }
}

Retrieves billing information for a specific server (container host) in the requestor’s account. Use refUUID whenever possible.

HTTP Request

GET $serverUrl/api/billing/servers/:refUUID|:id

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeTenants false Optional ability to include all subtenant billing information when calling from a master tenant user
accountId Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with “includeTenants=true” accountId is ignored

Billing For All Instances

curl "$serverUrl/api/billing/instances" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "price": 0.0,
    "cost": 0.0,
    "startDate": "2017-01-01T00:00:00Z",
    "endDate": "2017-01-31T23:59:59Z",
    "instances": [
      {
        "containers": [
                  {
            "usages": [
            ],
            "numUnits": 0.0,
            "unit": "hour",
            "name": "name"
          }
        ]
      }
    ]
  }
}

Retrieves billing information for all instances on the requestor’s account.

HTTP Request

GET $serverUrl/api/billing/instances

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeTenants false Optional ability to include all subtenant billing information when calling from a master tenant user
accountId Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with “includeTenants=true” accountId is ignored

Billing For a Specific Instance

curl "$serverUrl/api/billing/instances/cf31b12d-9aa9-4394-8fad-12a0fbc2515e" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "billingInfo": {
    "instanceId": 11,
    "instanceUUID": "cf31b12d-9aa9-4394-8fad-12a0fbc2515e",
    "startDate": "2017-01-01T00:00:00Z",
    "endDate": "2017-01-31T23:59:59Z",
    "name": "name",
    "price": 0,
    "cost": 0,
    "containers": [
      {
        "usages": [
          {
            "applicablePrices": [
            ]
          }
        ],
        "numUnits": 0.0,
        "unit": "hour",
        "name": "name"
      }
    ]
  }
}

Retrieves billing information for a instance in the requestor’s account. Use instanceUUID whenever possible.

HTTP Request

GET $serverUrl/api/billing/instances/:instanceUUID|:id

Query Parameters

Parameter Default Description
startDate Beginning of the current month
endDate Now
includeUsages true Optional ability to suppress the usage records
maxUsages null Optional ability to limit the usages returned
offsetUsages null Optional ability to offset the usages returned, for use with maxUsages to paginate
includeTenants false Optional ability to include all subtenant billing information when calling from a master tenant user
accountId Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with “includeTenants=true” accountId is ignored

Invoices

Provides API interfaces for viewing account invoices.

Get All Invoices

curl "$serverUrl/api/invoices" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "invoices": [
    {
      "id": 11868,
      "account": {
        "id": 1,
        "name": "root"
      },
      "group": {
        "id": 1,
        "name": "lonestar"
      },
      "cloud": {
        "id": 39,
        "name": "qa-amazon"
      },
      "instance": {
        "id": 331,
        "name": "nginx21"
      },
      "server": null,
      "cluster": null,
      "user": {
        "id": 1,
        "name": "admin"
      },
      "plan": {
        "id": 1,
        "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
      },
      "tags": [
        {
          "id": 714462,
          "name": "agency",
          "value": "Lonestar"
        },
        {
          "id": 714460,
          "name": "hello",
          "value": "world"
        }
      ],
      "project": {
        "id": 2,
        "name": "test",
        "tags": {
          "agency": "Lonestar"
        }
      },
      "refType": "Instance",
      "refId": 331,
      "refName": "nginx21",
      "refCategory": "vm",
      "resourceId": null,
      "resourceUuid": null,
      "resourceType": null,
      "resourceName": null,
      "resourceExternalId": null,
      "resourceInternalId": null,
      "interval": "month",
      "period": "202005",
      "estimate": false,
      "active": true,
      "startDate": "2020-05-01T04:00:00+0000",
      "endDate": "2020-06-01T03:59:59+0000",
      "refStart": "2020-05-01T04:00:00+0000",
      "refEnd": "2020-06-01T03:59:59+0000",
      "estimatedComputePrice": 0.0,
      "estimatedComputeCost": 0.0,
      "estimatedMemoryPrice": 0.0,
      "estimatedMemoryCost": 0.0,
      "estimatedStoragePrice": 0.0,
      "estimatedStorageCost": 0.0,
      "estimatedNetworkPrice": 0.0,
      "estimatedNetworkCost": 0.0,
      "estimatedLicensePrice": 0.0,
      "estimatedLicenseCost": 0.0,
      "estimatedExtraPrice": 0.0,
      "estimatedExtraCost": 0.0,
      "estimatedTotalPrice": 6.250800024,
      "estimatedTotalCost": 6.250800024,
      "estimatedRunningPrice": 1.5038869430406268,
      "estimatedRunningCost": 1.5038869430406268,
      "estimatedCurrency": "USD",
      "estimatedConversionRate": 1.0,
      "actualComputePrice": 0.1709403426,
      "actualComputeCost": 0.1709403426,
      "actualMemoryPrice": 0.0,
      "actualMemoryCost": 0.0,
      "actualStoragePrice": 0.0,
      "actualStorageCost": 0.0,
      "actualNetworkPrice": 0.0,
      "actualNetworkCost": 0.0,
      "actualLicensePrice": 0.0,
      "actualLicenseCost": 0.0,
      "actualExtraPrice": 0.0,
      "actualExtraCost": 0.0,
      "actualTotalPrice": 0.7105014791842815,
      "actualTotalCost": 0.7105014791842815,
      "actualRunningPrice": 0.1709403426,
      "actualRunningCost": 0.1709403426,
      "actualCurrency": "USD",
      "actualConversionRate": 1.0,
      "computePrice": 0.1709403426,
      "computeCost": 0.1709403426,
      "memoryPrice": 0.0,
      "memoryCost": 0.0,
      "storagePrice": 0.0,
      "storageCost": 0.0,
      "networkPrice": 0.0,
      "networkCost": 0.0,
      "licensePrice": 0.0,
      "licenseCost": 0.0,
      "extraPrice": 0.0,
      "extraCost": 0.0,
      "totalPrice": 0.7105014791842815,
      "totalCost": 0.7105014791842815,
      "runningPrice": 0.1709403426,
      "runningCost": 0.1709403426,
      "currency": "USD",
      "conversionRate": 1.0,
      "costType": "actual",
      "offTime": 0,
      "powerState": "on",
      "powerDate": "2020-05-01T04:00:00+0000",
      "runningMultiplier": 0.2405911143,
      "lastCostDate": "2020-05-08T14:59:59+0000",
      "lastActualDate": "2020-05-08T14:59:59+0000",
      "dateCreated": "2020-05-01T15:59:49+0000",
      "lastUpdated": "2020-05-08T15:00:08+0000",
      "lineItemCount": 0
    }
  ],
  "meta": {
    "size": 25,
    "total": 35021,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves a list of invoices for the specified parameters.

HTTP Request

GET $serverUrl/api/invoices

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort startDate desc Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on refName
name If specified will return an exact match on refName
startDate Only return records with a startDate greater than or equal to the specified date. Format is YYYY-MM-DD.
endDate Only return records with an endDate less than or equal to the specified date. Format is YYYY-MM-DD.
period Only return records for period that matches with the specified value. This is an alternative to using startDate/endDate. Format is YYYY or YYYYMM.
refType If specified will return an exact match on refType. eg. ComputeSite (Group), ComputeZone (Cloud), ComputeServer (Host), Instance, Container, User.
refId If specified will return an exact match on refId
refStatus If specified, will filter on the associated StorageVolume status. eg. provisioned or unattached. This is only applicable when refType=StorageVolume.
zoneId If specified will return an exact match on zone (cloud) ID
siteId If specified will return an exact match on site (group) ID
instanceId If specified will return an exact match on instance ID
containerId If specified will return an exact match on container ID
serverId If specified will return an exact match on server (host) ID
userId If specified will return an exact match on user ID
projectId If specified will return an exact match on project ID
active If specified will return an exact match on active flag.
accountId (own account) Allows master tenant users to view invoices for another tenant.
includeLineItems false Pass true to include the list of lineItems for each invoice, only lineItemCount is returned by default.
includeTotals false Pass true to include the summed totals (cost/price values) for all the invoices found in the query. The returned property is called invoiceTotals.
tags Filter by tags (metadata). This allows filtering by a tag name and value(s) like this tags.env=qa or tags.env=qa&tags.env=test which matches both: env=qa or env=test.

Get a Specific Invoice

curl "$serverUrl/api/invoices/11868" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "invoice": {
    "id": 11868,
    "account": {
      "id": 1,
      "name": "root"
    },
    "group": {
      "id": 1,
      "name": "lonestar"
    },
    "cloud": {
      "id": 39,
      "name": "qa-amazon"
    },
    "instance": {
      "id": 331,
      "name": "nginx21"
    },
    "server": null,
    "cluster": null,
    "user": {
      "id": 1,
      "name": "admin"
    },
    "plan": {
      "id": 1,
      "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
    },
    "tags": [
      {
        "id": 714462,
        "name": "agency",
        "value": "Lonestar"
      },
      {
        "id": 714460,
        "name": "hello",
        "value": "world"
      }
    ],
    "project": {
      "id": 2,
      "name": "test",
      "tags": {
        "agency": "Lonestar"
      }
    },
    "refType": "Instance",
    "refId": 331,
    "refName": "nginx21",
    "refCategory": "vm",
    "resourceId": null,
    "resourceUuid": null,
    "resourceType": null,
    "resourceName": null,
    "resourceExternalId": null,
    "resourceInternalId": null,
    "interval": "month",
    "period": "202005",
    "estimate": false,
    "active": true,
    "startDate": "2020-05-01T04:00:00+0000",
    "endDate": "2020-06-01T03:59:59+0000",
    "refStart": "2020-05-01T04:00:00+0000",
    "refEnd": "2020-06-01T03:59:59+0000",
    "estimatedComputePrice": 0.0,
    "estimatedComputeCost": 0.0,
    "estimatedMemoryPrice": 0.0,
    "estimatedMemoryCost": 0.0,
    "estimatedStoragePrice": 0.0,
    "estimatedStorageCost": 0.0,
    "estimatedNetworkPrice": 0.0,
    "estimatedNetworkCost": 0.0,
    "estimatedLicensePrice": 0.0,
    "estimatedLicenseCost": 0.0,
    "estimatedExtraPrice": 0.0,
    "estimatedExtraCost": 0.0,
    "estimatedTotalPrice": 6.250800024,
    "estimatedTotalCost": 6.250800024,
    "estimatedRunningPrice": 1.5038869430406268,
    "estimatedRunningCost": 1.5038869430406268,
    "estimatedCurrency": "USD",
    "estimatedConversionRate": 1.0,
    "actualComputePrice": 0.1709403426,
    "actualComputeCost": 0.1709403426,
    "actualMemoryPrice": 0.0,
    "actualMemoryCost": 0.0,
    "actualStoragePrice": 0.0,
    "actualStorageCost": 0.0,
    "actualNetworkPrice": 0.0,
    "actualNetworkCost": 0.0,
    "actualLicensePrice": 0.0,
    "actualLicenseCost": 0.0,
    "actualExtraPrice": 0.0,
    "actualExtraCost": 0.0,
    "actualTotalPrice": 0.7105014791842815,
    "actualTotalCost": 0.7105014791842815,
    "actualRunningPrice": 0.1709403426,
    "actualRunningCost": 0.1709403426,
    "actualCurrency": "USD",
    "actualConversionRate": 1.0,
    "computePrice": 0.1709403426,
    "computeCost": 0.1709403426,
    "memoryPrice": 0.0,
    "memoryCost": 0.0,
    "storagePrice": 0.0,
    "storageCost": 0.0,
    "networkPrice": 0.0,
    "networkCost": 0.0,
    "licensePrice": 0.0,
    "licenseCost": 0.0,
    "extraPrice": 0.0,
    "extraCost": 0.0,
    "totalPrice": 0.7105014791842815,
    "totalCost": 0.7105014791842815,
    "runningPrice": 0.1709403426,
    "runningCost": 0.1709403426,
    "currency": "USD",
    "conversionRate": 1.0,
    "costType": "actual",
    "offTime": 0,
    "powerState": "on",
    "powerDate": "2020-05-01T04:00:00+0000",
    "runningMultiplier": 0.2405911143,
    "lastCostDate": "2020-05-08T14:59:59+0000",
    "lastActualDate": "2020-05-08T14:59:59+0000",
    "dateCreated": "2020-05-01T15:59:49+0000",
    "lastUpdated": "2020-05-08T15:00:08+0000",
    "lineItems": [

    ]
  }
}

This endpoint retrieves a specific invoice.

HTTP Request

GET $serverUrl/api/invoices/:id

URL Parameters

Parameter Description
id ID of the invoice

Update Invoice Tags

curl -XPUT "$serverUrl/api/invoices/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "invoice": {
  "addTags": [
    {"name": "hello", "value": "world"}
  ],
  "removeTags": [
    {"name": "oldTag"}
  ]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a specific invoice

This endpoint allows updating the tags for a specific invoice. Invoice tags are automatically set to match the tags of the associated resource (ComputeServer/Instance/Container).

HTTP Request

PUT $serverUrl/api/invoices/:id

JSON Invoice Parameters

Parameter Default Description
tags Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified.
addTags Add or update value of Metadata tags, Array of objects having a name and value
removeTags Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed.

Get All Invoice Line Items

curl "$serverUrl/api/invoice-line-items" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "lineItems": [
    {
      "id": 3247,
      "invoiceId": 12347,
      "refType": "AccountResource",
      "refId": 3,
      "refName": "ocid1.instance.oc1.iad.abuwcljsdtocgl7wumoxflvd7725dobh3zk2s3rdmtnp5ixt2x7nc3awllda",
      "refCategory": "invoice",
      "startDate": "2020-05-09T22:00:00+0000",
      "endDate": "2020-05-09T23:00:00+0000",
      "itemId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi3BHgE1epCBn5P5XcuFSmUd",
      "itemType": null,
      "itemName": "ocid1.instance.oc1.iad.abuwcljsdtocgl7wumoxflvd7725dobh3zk2s3rdmtnp5ixt2x7nc3awllda",
      "itemDescription": null,
      "productId": null,
      "productCode": "B88514",
      "productName": null,
      "itemSeller": null,
      "itemAction": null,
      "externalId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi3BHgE1epCBn5P5XcuFSmUd",
      "rateId": null,
      "rateClass": null,
      "rateUnit": "0.0638",
      "rateTerm": null,
      "usageType": "Virtual Machine Standard - X7",
      "usageCategory": "compute",
      "itemUsage": 1.0,
      "itemRate": 0.0,
      "itemCost": 0.0638,
      "itemPrice": 0.0638,
      "itemTax": 0.0,
      "itemTerm": null,
      "taxType": null,
      "dateCreated": "2020-05-12T02:29:54+0000",
      "lastUpdated": "2020-05-12T02:29:54+0000"
    },
    {
      "id": 3246,
      "invoiceId": 12431,
      "refType": "AccountResource",
      "refId": 2139,
      "refName": "ow-oraclecloud-1",
      "refCategory": "invoice",
      "startDate": "2020-05-09T21:00:00+0000",
      "endDate": "2020-05-09T22:00:00+0000",
      "itemId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
      "itemType": null,
      "itemName": "ow-oraclecloud-1",
      "itemDescription": null,
      "productId": null,
      "productCode": "B91962",
      "productName": null,
      "itemSeller": null,
      "itemAction": null,
      "externalId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
      "rateId": null,
      "rateClass": null,
      "rateUnit": "0.0017",
      "rateTerm": null,
      "usageType": "Block Volume - Performance Units",
      "usageCategory": "storage",
      "itemUsage": 0.672043008681,
      "itemRate": 0.0,
      "itemCost": 0.001142473117,
      "itemPrice": 0.001142473117,
      "itemTax": 0.0,
      "itemTerm": null,
      "taxType": null,
      "dateCreated": "2020-05-11T08:47:06+0000",
      "lastUpdated": "2020-05-11T08:47:06+0000"
    }
  ],
  "meta": {
    "size": 2,
    "total": 3269,
    "offset": 22,
    "max": 25
  }
}

This endpoint retrieves all invoice line items for the specified parameters.

HTTP Request

GET $serverUrl/api/invoice-line-items

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort startDate desc Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase If specified will return a partial match on refName
name If specified will return an exact match on refName
startDate Only return records with a startDate greater than or equal to the specified date. Format is YYYY-MM-DD.
endDate Only return records with an endDate less than or equal to the specified date. Format is YYYY-MM-DD.
period Only return records for period that matches with the specified value. This is an alternative to using startDate/endDate. Format is YYYY or YYYYMM.
refType If specified will return an exact match on refType. eg. ComputeSite (Group), ComputeZone (Cloud), ComputeServer (Host), Instance, Container, User.
refId If specified will return an exact match on refId
zoneId If specified will return an exact match on zone (cloud) ID
siteId If specified will return an exact match on site (group) ID
instanceId If specified will return an exact match on instance ID
containerId If specified will return an exact match on container ID
serverId If specified will return an exact match on server (host) ID
userId If specified will return an exact match on user ID
projectId If specified will return an exact match on project ID
active If specified will return an exact match on active flag.
includeTotals false If true, invoiceTotals is returned containing sums of all the cost and prices for all the invoices found.
accountId (own account) Allows master tenant users to view invoices for another tenant.
includeTotals false Pass true to include the summed totals (cost/price values) for all the invoices found in the query. The returned property is called lineItemTotals.

Get a Specific Invoice Line Item

curl "$serverUrl/api/invoice-line-items/678" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "lineItem": {
    "id": 3246,
    "invoiceId": 12431,
    "refType": "AccountResource",
    "refId": 2139,
    "refName": "ow-oraclecloud-1",
    "refCategory": "invoice",
    "startDate": "2020-05-09T21:00:00+0000",
    "endDate": "2020-05-09T22:00:00+0000",
    "itemId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
    "itemType": null,
    "itemName": "ow-oraclecloud-1",
    "itemDescription": null,
    "productId": null,
    "productCode": "B91962",
    "productName": null,
    "itemSeller": null,
    "itemAction": null,
    "externalId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
    "rateId": null,
    "rateClass": null,
    "rateUnit": "0.0017",
    "rateTerm": null,
    "usageType": "Block Volume - Performance Units",
    "usageCategory": "storage",
    "itemUsage": 0.672043008681,
    "itemRate": 0.0,
    "itemCost": 0.001142473117,
    "itemPrice": 0.001142473117,
    "itemTax": 0.0,
    "itemTerm": null,
    "taxType": null,
    "dateCreated": "2020-05-11T08:47:06+0000",
    "lastUpdated": "2020-05-11T08:47:06+0000"
  }
}

This endpoint retrieves a specific invoice.

HTTP Request

GET $serverUrl/api/invoice-line-items/:id

URL Parameters

Parameter Description
id ID of the invoice line item

Projects

Morpheus provides a database for keeping track of Projects in the system. Projects can be used to associate resources together and assign common metadata tags to their invoices.

Get All Projects

curl "$serverUrl/api/projects"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "projects": [
    {
      "id": 1,
      "name": "test",
      "description": "api test",
      "owner": {
        "id": 1,
        "username": "admin"
      },
      "tags": [
        {
          "id": 18028,
          "name": "foo",
          "value": "bar"
        }
      ],
      "instances": [
        {
          "id": 303,
          "name": "ubuntutest"
        }
      ],
      "servers": [

      ],
      "clouds": [
        {
          "id": 39,
          "name": "qa-amazon"
        }
      ],
      "dateCreated": "2020-05-05T17:11:16+0000",
      "lastUpdated": "2020-05-06T16:06:31+0000"
    },
    {
      "id": 2,
      "name": "uno",
      "description": "a test project about pizza",
      "owner": {
        "id": 1,
        "username": "admin"
      },
      "tags": [
        {
          "id": 18115,
          "name": "pizzeria",
          "value": "uno"
        },
        {
          "id": 18117,
          "name": "planet",
          "value": "saturn"
        },
        {
          "id": 18116,
          "name": "taste",
          "value": "delicious"
        }
      ],
      "instances": [
        {
          "id": 344,
          "name": "nginx21"
        }
      ],
      "servers": [
      ],
      "clouds": [
        {
          "id": 32,
          "name": "qa-google"
        }
      ],
      "dateCreated": "2020-05-07T03:00:02+0000",
      "lastUpdated": "2020-05-07T03:10:51+0000"
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all projects associated with the account.

HTTP Request

GET $serverUrl/api/projects

Query Parameters

Parameter Default Description
phrase Filter on partial match of name or description
name Filter on exact match of name
instanceId Filter by associated Instance
serverId Filter by associated Server
cloudId Filter by associated Cloud
resourceId Filter by associated AccountResource(s). These are discovered AccountResource records that do not belong to known instances or servers.
ownerId Filter by owner
id Filter by Project id(s)

Get a Specific Project

curl "$serverUrl/api/projects/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "project": {
    "id": 19,
    "name": "uno",
    "description": "a test project about pizza",
    "owner": {
      "id": 1,
      "username": "james"
    },
    "tags": [
      {
        "id": 18115,
        "name": "pizzeria",
        "value": "uno"
      },
      {
        "id": 18117,
        "name": "planet",
        "value": "saturn"
      },
      {
        "id": 18116,
        "name": "taste",
        "value": "delicious"
      }
    ],
    "instances": [
      {
        "id": 344,
        "name": "nginx21"
      }
    ],
    "servers": [
    ],
    "clouds": [
      {
        "id": 32,
        "name": "qa-google"
      }
    ],
    "dateCreated": "2020-05-07T03:00:02+0000",
    "lastUpdated": "2020-05-07T03:10:51+0000"
  }
}

This endpoint retrieves a specific project.

HTTP Request

GET $serverUrl/api/projects/:id

URL Parameters

Parameter Description
ID The ID of the project

Create a Project

curl -XPOST "$serverUrl/api/projects" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"project":{
    "name": "Test Project",
    "description": "a test project",
    "tags": {"hello":"world"},
    "instances":[
        {"id":1}, {"id":2}, {"id":3}
    ]
  }}'

The above command returns JSON structured like getting a single project:

Create a new project.

HTTP Request

POST $serverUrl/api/projects

JSON Parameters

Parameter Default Description
name A unique name for your project
description Description
tags Metadata tags, Array of objects having a name and value
instances Instances, Array of objects having an id
servers Servers, Array of objects having an id
clouds Clouds, Array of objects having an id
resources Resources, Array of objects having an id. These are discovered AccountResource records that do not belong to known instances or servers.

Update a Project

curl -XPUT "$serverUrl/api/projects/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"project":{
    "addInstances":[
        {"id":4}, {"id":5}, {"id":6}
    ]
  }}'

The above command returns JSON structured like getting a single project:

Update an existing project.

HTTP Request

PUT $serverUrl/api/projects/:id

URL Parameters

Parameter Description
ID The ID of the project

JSON Parameters

Parameter Default Description
name A unique name for your project
description Description
tags Metadata tags, Array of objects having a name and value
addTags Add or update value of Metadata tags, Array of objects having a name and value
removeTags Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed.
instances Instances, Array of objects having an id
servers Servers, Array of objects having an id
clouds Clouds, Array of objects having an id
addInstances Add Instances to the project, Array of objects having an id
removeInstances Remove Instances from the project, Array of objects having an id
addServers Add Servers to the project, Array of objects having an id
removeServers Remove Servers to remove from the project, Array of objects having an id
addClouds Add Clouds to the project, Array of objects having an id
removeClouds Remove Clouds from the project, Array of objects having an id
resources Resources, Array of objects having an id. These are discovered AccountResource records that do not belong to known instances or servers.
addResources Add Resources to the project, Array of objects having an id
removeResources Remove Resources from the project, Array of objects having an id

Delete a Project

curl -XDELETE "$serverUrl/api/projects/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Delete a project from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/projects/:id

URL Parameters

Parameter Description
ID The ID of the project

History

Provides API interfaces for viewing the process history for instances.

Get All Processes

curl "$serverUrl/api/processes" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "processes": [
    {
      "id": 250,
      "accountId": 1,
      "uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
      "processType": {
        "code": "provision",
        "name": "provision"
      },
      "description": null,
      "subType": null,
      "subId": null,
      "zoneId": 34,
      "integrationId": null,
      "instanceId": 238,
      "containerId": 240,
      "serverId": 601,
      "containerName": "apachetest",
      "displayName": "apachetest",
      "timerCategory": "vmware",
      "timerSubCategory": "28",
      "status": "failed",
      "reason": null,
      "percent": 100.0,
      "statusEta": 348246,
      "message": null,
      "output": null,
      "error": null,
      "startDate": "2018-09-28T19:10:56+0000",
      "endDate": "2018-09-28T20:21:49+0000",
      "duration": 4253127,
      "dateCreated": "2018-09-28T19:10:56+0000",
      "lastUpdated": "2018-09-28T20:21:49+0000",
      "createdBy": {
        "username": "admin",
        "displayName": "Admin"
      },
      "updatedBy": {
        "username": "admin",
        "displayName": "Admin"
      },
      "events": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all processes.

HTTP Request

GET $serverUrl/api/processes

Query Parameters

Parameter Default Description
phrase If specified will return a partial match on displayName, message or output
instanceId Filter by instance id(s)
containerId Filter by container id(s)
serverId Filter by server id(s)
zoneId Filter by zone id(s)
appId Filter by app id(s)

Get a Specific Process

curl "$serverUrl/api/processes/250" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "process": {
    "id": 250,
    "accountId": 1,
    "uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
    "processType": {
      "code": "provision",
      "name": "provision"
    },
    "description": null,
    "subType": null,
    "subId": null,
    "zoneId": 34,
    "integrationId": null,
    "instanceId": 238,
    "containerId": 240,
    "serverId": 601,
    "containerName": "apachetest",
    "displayName": "apachetest",
    "timerCategory": "vmware",
    "timerSubCategory": "28",
    "status": "failed",
    "reason": null,
    "percent": 100.0,
    "statusEta": 348246,
    "message": null,
    "output": null,
    "error": null,
    "startDate": "2018-09-28T19:10:56+0000",
    "endDate": "2018-09-28T20:21:49+0000",
    "duration": 4253127,
    "dateCreated": "2018-09-28T19:10:56+0000",
    "lastUpdated": "2018-09-28T20:21:49+0000",
    "createdBy": {
      "username": "admin",
      "displayName": "Admin"
    },
    "updatedBy": {
      "username": "admin",
      "displayName": "Admin"
    },
    "events": [
      {
        "id": 940,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "54bf6265-1e86-45b4-b1a7-d4b198b13c45",
        "processType": {
          "code": "provisionResources",
          "name": "prepare resources"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:10:56+0000",
        "endDate": "2018-09-28T19:10:57+0000",
        "duration": 921,
        "dateCreated": "2018-09-28T19:10:56+0000",
        "lastUpdated": "2018-09-28T19:10:57+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 941,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "9a9791b7-0091-4ba7-be4d-e1586be3078c",
        "processType": {
          "code": "provisionImage",
          "name": "prepare image"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:10:57+0000",
        "endDate": "2018-09-28T19:11:01+0000",
        "duration": 3645,
        "dateCreated": "2018-09-28T19:10:57+0000",
        "lastUpdated": "2018-09-28T19:11:01+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 942,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "f1905796-9387-4983-ae0d-0fee5bb81f56",
        "processType": {
          "code": "provisionConfig",
          "name": "configure instance"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:11:01+0000",
        "endDate": "2018-09-28T19:11:01+0000",
        "duration": 28,
        "dateCreated": "2018-09-28T19:11:01+0000",
        "lastUpdated": "2018-09-28T19:11:01+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 943,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "599a0c2d-491c-4178-8b86-55b6d019d48c",
        "processType": {
          "code": "provisionDeploy",
          "name": "deploy instance"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:11:01+0000",
        "endDate": "2018-09-28T19:11:33+0000",
        "duration": 32219,
        "dateCreated": "2018-09-28T19:11:01+0000",
        "lastUpdated": "2018-09-28T19:11:33+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 944,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "4f4088b0-7043-4a35-82c1-00456643beaa",
        "processType": {
          "code": "provisionResize",
          "name": "resize instance"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:11:33+0000",
        "endDate": "2018-09-28T19:11:36+0000",
        "duration": 2896,
        "dateCreated": "2018-09-28T19:11:33+0000",
        "lastUpdated": "2018-09-28T19:11:36+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 945,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "10559e2a-6980-4443-afd4-37b7471492ba",
        "processType": {
          "code": "provisionCloudInit",
          "name": "configure cloud init"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:11:36+0000",
        "endDate": "2018-09-28T19:11:42+0000",
        "duration": 6152,
        "dateCreated": "2018-09-28T19:11:36+0000",
        "lastUpdated": "2018-09-28T19:11:42+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 946,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "0081e523-bfea-4664-b582-d68076943a46",
        "processType": {
          "code": "provisionLaunch",
          "name": "power on"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "complete",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:11:42+0000",
        "endDate": "2018-09-28T19:11:45+0000",
        "duration": 2549,
        "dateCreated": "2018-09-28T19:11:42+0000",
        "lastUpdated": "2018-09-28T19:11:45+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      },
      {
        "id": 947,
        "processId": 250,
        "accountId": 1,
        "uniqueId": "de66729e-9580-43b0-950c-f2769cd86790",
        "processType": {
          "code": "provisionNetwork",
          "name": "network wait"
        },
        "description": null,
        "refType": "container",
        "refId": 240,
        "subType": null,
        "subId": null,
        "zoneId": 34,
        "integrationId": null,
        "instanceId": 238,
        "containerId": 240,
        "serverId": 601,
        "containerName": "apachetest",
        "displayName": "apachetest",
        "status": "failed",
        "reason": null,
        "percent": 100.0,
        "statusEta": 348246,
        "message": null,
        "output": null,
        "error": null,
        "startDate": "2018-09-28T19:11:45+0000",
        "endDate": "2018-09-28T20:21:49+0000",
        "duration": 4204122,
        "dateCreated": "2018-09-28T19:11:45+0000",
        "lastUpdated": "2018-09-28T20:21:49+0000",
        "createdBy": {
          "username": "admin",
          "displayName": "Admin"
        },
        "updatedBy": {
          "username": "admin",
          "displayName": "Admin"
        }
      }
    ]
  }
}

This endpoint retrieves a specific process.

HTTP Request

GET $serverUrl/api/processes/:id

URL Parameters

Parameter Description
ID The ID of the process

Get a Specific Process Event

curl "$serverUrl/api/processes/events/940" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "processEvent": {
    "id": 940,
    "processId": 250,
    "accountId": 1,
    "uniqueId": "54bf6265-1e86-45b4-b1a7-d4b198b13c45",
    "processType": {
      "code": "provisionResources",
      "name": "prepare resources"
    },
    "description": null,
    "refType": "container",
    "refId": 240,
    "subType": null,
    "subId": null,
    "zoneId": 34,
    "integrationId": null,
    "instanceId": 238,
    "containerId": 240,
    "serverId": 601,
    "containerName": "apachetest",
    "displayName": "apachetest",
    "status": "complete",
    "reason": null,
    "percent": 100.0,
    "statusEta": 348246,
    "message": null,
    "output": null,
    "error": null,
    "startDate": "2018-09-28T19:10:56+0000",
    "endDate": "2018-09-28T19:10:57+0000",
    "duration": 921,
    "dateCreated": "2018-09-28T19:10:56+0000",
    "lastUpdated": "2018-09-28T19:10:57+0000",
    "createdBy": {
      "username": "admin",
      "displayName": "Admin"
    },
    "updatedBy": {
      "username": "admin",
      "displayName": "Admin"
    }
  }
}

This endpoint retrieves a specific process event.

HTTP Request

GET $serverUrl/api/processes/events/:id

URL Parameters

Parameter Description
ID The ID of the process event

Health

Provides API interfaces for checking health status. This is the status of the Morpheus appliance itself, which includes elasticsearch, mysql etc.

Get Health Status

curl "$serverUrl/api/health" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "health": {
    "success": true,
    "date": "2019-12-23T19:14:41Z",
    "cpu": {
      "success": true,
      "cpuLoad": 0.5126493909536541,
      "cpuTotalLoad": 5.302748759909017,
      "processorCount": 16,
      "processTime": 52169711.18,
      "systemLoad": 2.9423828125,
      "status": "ok"
    },
    "memory": {
      "success": true,
      "maxMemory": 7635730432,
      "totalMemory": 6765936640,
      "freeMemory": 197682472,
      "usedMemory": 6568254168,
      "systemMemory": 34359738368,
      "comittedMemory": 18334928896,
      "systemFreeMemory": 474562560.0,
      "systemSwap": 34359738368,
      "systemFreeSwap": 34359738368,
      "swapPercent": 0.0,
      "memoryPercent": 0.9707826894,
      "systemMemoryPercent": 0.9861884117126465,
      "status": "warning",
      "statusMessage": "heavy memory usage, consider increasing memory"
    }
}

The above JSON is abbreviated, the actual response contains more data.

This endpoint retrieves health info about the Morpheus appliance such as cpu, memory and database usage. Elasticsearch statistics and queue usage are also returned.

HTTP Request

GET $serverUrl/api/health

Get All Health Alarms

curl "$serverUrl/api/health/alarms" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "alarms": [

  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all health alarms, which are Operation notifications from Cloud and other Service Integrations. These alarms are not generated by Morpheus but synced and displayed for visibility in Morpheus. By default only open alarms are returned. Open alarms are those that have not yet been acknowledged.

HTTP Request

GET $serverUrl/api/health/alarms

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by matching name
name Filter by name
acknowledged Filter by acknowledged flag

Get a Specific Health Alarm

curl "$serverUrl/api/health/alarms/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "alarm": {
    "id": 1,
    "name": "foobar",
    "dateCreated": "2019-11-17T05:59:20+0000",
    "lastUpdated": "2019-11-17T05:59:20+0000"
  }
}

This endpoint will retrieve a specific health alarm by ID.

HTTP Request

GET $serverUrl/api/health/alarms/:id

URL Parameters

Parameter Description
ID The ID of the alarm

Acknowledge a Health Alarm

curl -XPUT "$serverUrl/api/health/alarms/1/acknowledge" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"alarm":{
    "acknowledged": true,
  }}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint acknowledge the specified health alarm. This marks it as acknowledged so it will no longer appear in the list of open alarms.

HTTP Request

PUT $serverUrl/api/health/alarms/1/acknowledge

URL Parameters

Parameter Description
ID The ID of the alarm

JSON Parameters

The following parameters are passed inside an object named alarm.

Parameter Default Description
acknowledged Pass true to ackowledge an alarm, or pass false to unacknowledge it.

Acknowledge Many Health Alarms

curl -XPUT "$serverUrl/api/health/alarms/acknowledge" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [1,2,3,4,5],
    "alarm":{
      "acknowledged": true
  }}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint acknowledges health alarms. It allows many alarms to be acknowledged at once by specifying ids, or acknowledging all alarms via the all flag.

HTTP Request

PUT $serverUrl/api/health/alarms/acknowledge

JSON Parameters

Parameter Default Description
ids [] Array of Alarm ID(s)to be updated.
all false Pass true to update all alarms instead of passing ids. This will update any active alarm that is not already acknowledged.
acknowledged true Pass false to unacknowledge the alarm(s) instead of acknowledge them.

Get All Health Logs

curl "$serverUrl/api/health/logs" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "logs": [
    {
      "typeCode": "appliance",
      "ts": "2020-01-05T03:09:04Z",
      "level": "ERROR",
      "sourceType": "appliance",
      "message": "[pool-2-thread-7] Failure in api call",
      "hostname": "labs-den-m1",
      "objectId": "1",
      "seq": 106678,
      "_id": "324c518d-eb37-41d8-bf13-1cec8bfa0b05"
    },
    {
      "typeCode": "appliance",
      "ts": "2020-01-05T03:08:59Z",
      "level": "INFO",
      "sourceType": "appliance",
      "message": "[pool-2-thread-7] duplicate key: 9825f604-7dd0-4c5f-b1c2-f3e0769bd95c total: 2 remove count: 2",
      "hostname": "labs-den-m1",
      "objectId": "1",
      "seq": 106522,
      "_id": "e97faab1-32c7-4d08-8025-34f12776c583"
    }
  ],
  "meta": {
    "size": 2,
    "total": 10000,
    "max": "2",
    "offset": 0
  }
}

This endpoint retrieves all health logs. These are the logs of the remote appliance itself. These logs show all ui activity and are useful for troubleshooting and auditing. Stack traces are filtered for Morpheus services. Complete stack traces can be found in /var/log/morpheus/morpheus-ui/current.

HTTP Request

GET $serverUrl/api/health/logs

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort ts Sort order
direction desc Sort direction
phrase Filter by wildcard search of fields
startDate 24 hours ago Date filter in standard iso8601 format, restricts query to only load logs updated more recently than the date specified.
endDate Date filter in standard iso8601 format, restricts query to only load logs updated before the date specified.

Export Health Logs

curl "$serverUrl/api/health/logs/export" \
  -H "Authorization: BEARER $accessToken"

The above command returns Content-Type: "application/octet-stream" and Content-disposition: attachment;filename="morpheus-2021-11-17-03-56-03.log".

This endpoint downloads the morpheus appliance logs as a file attachment. By default, the most recent 10,000 log entries are returned, with the newest at the end of the file. The format for each log entry is [$timestamp] $level $message.

HTTP Request

GET $serverUrl/api/health/logs/export

Query Parameters

Parameter Default Description
max 10000 Max number of results to return
offset 0 Offset of records you want to load
sort ts Sort order
direction desc Sort direction
reverse true Reverse order of records. this true by default when sort and direction are not passed, but false by default if either is passed. This means that by default the newest log entries are the bottom of the file.
phrase Filter by wildcard search of fields
startDate 24 hours ago Date filter in standard iso8601 format, restricts query to only load logs updated more recently than the date specified.
endDate Date filter in standard iso8601 format, restricts query to only load logs updated before the date specified.

Guidance

Provides API interfaces for managing guidance within Morpheus.

Get All Discoveries

curl "$serverUrl/api/guidance" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "discoveries": [
    {
      "id": 3405,
      "dateCreated": "2019-03-05T23:05:02+0000",
      "lastUpdated": "2020-03-21T00:05:05+0000",
      "actionCategory": "reservation",
      "actionMessage": "Reservation recommentations",
      "actionTitle": "reserve.compute",
      "actionType": "reserve",
      "actionValue": "34.519463385782942",
      "actionValueType": "reservation",
      "actionPlanId": null,
      "statusMessage": "Reservation recommendations for cloud QA Azure",
      "accountId": 1,
      "userId": null,
      "siteId": 2,
      "zone": {
        "id": 4,
        "name": "QA Azure",
        "zoneType": {
          "id": 9,
          "name": "Azure (Public)"
        }
      },
      "state": "processed",
      "stateMessage": "shutdown resource",
      "severity": "info",
      "resolved": false,
      "resolvedMessage": null,
      "refType": "computeZone",
      "refId": 4,
      "refName": "QA Azure",
      "type": {
        "id": 6,
        "name": "Reservation Recommendation",
        "code": "reservations",
        "title": "Add Reservations"
      },
      "savings": {
        "amount": 34.51946338578294,
        "currency": "USD"
      },
      "config": {
        "success": true,
        "detailList": [
          {
            "id": "billingAccount/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Consumption/reservationRecommendations/90bfe546-0ea4-8e62-4afb-975bbc9e83ac",
            "apiName": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "apiType": "Microsoft.Consumption/reservationRecommendations",
            "externalId": "Standard_D2",
            "period": "Last30Days",
            "name": "Standard_D2",
            "type": "Standard_D2",
            "category": "Standard_D2",
            "size": "Standard_D2 (Cores: 2, Memory: 7 GB) (eastus)",
            "region": "westus",
            "term": "P1Y",
            "meterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "onDemandCount": 0,
            "onDemandCost": 110.99038119400001,
            "reservedCount": 0,
            "reservedCost": 0,
            "recommendedCount": 1,
            "recommendedCost": 76.47091780821707,
            "totalSavings": 34.51946338578294,
            "totalSavingsPercent": 0.311013107752521
          }
        ],
        "services": {
          "azureVms": {
            "code": "azureVms",
            "name": "Azure Virtual Machines",
            "paymentOptions": {
              "NO_UPFRONT": {
                "code": "NO_UPFRONT",
                "name": "No Upfront",
                "termOptions": {
                  "{code=P1Y, name=1 Year, defaultOption=true}": {
                    "code": "P1Y",
                    "name": "1 Year",
                    "detailList": [
                      {
                        "id": "billingAccount/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Consumption/reservationRecommendations/90bfe546-0ea4-8e62-4afb-975bbc9e83ac",
                        "apiName": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "apiType": "Microsoft.Consumption/reservationRecommendations",
                        "externalId": "Standard_D2",
                        "period": "Last30Days",
                        "name": "Standard_D2",
                        "type": "Standard_D2",
                        "category": "Standard_D2",
                        "size": "Standard_D2 (Cores: 2, Memory: 7 GB) (eastus)",
                        "region": "westus",
                        "term": "P1Y",
                        "meterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx5",
                        "onDemandCount": 0,
                        "onDemandCost": 110.99038119400001,
                        "reservedCount": 0,
                        "reservedCost": 0,
                        "recommendedCount": 1,
                        "recommendedCost": 76.47091780821707,
                        "totalSavings": 34.51946338578294,
                        "totalSavingsPercent": 0.311013107752521
                      }
                    ],
                    "summary": {
                      "totalSavings": 34.51946338578294,
                      "currencyCode": "USD",
                      "totalSavingsPercent": 0.311013107752521,
                      "term": "",
                      "paymentOption": "",
                      "service": "compute",
                      "onDemandCount": 0,
                      "onDemandCost": 110.99038119400001,
                      "reservedCount": 0,
                      "reservedCost": 0,
                      "recommendedCount": 1,
                      "recommendedCost": 76.47091780821707
                    }
                  },
                  "{code=P3Y, name=3 Year}": {
                    "code": "P3Y",
                    "name": "3 Year",
                    "detailList": [
                      {
                        "id": "billingAccount/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Consumption/reservationRecommendations/90bfe546-0ea4-8e62-4afb-975bbc9e83ac",
                        "apiName": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "apiType": "Microsoft.Consumption/reservationRecommendations",
                        "externalId": "Standard_D2",
                        "period": "Last30Days",
                        "name": "Standard_D2",
                        "type": "Standard_D2",
                        "category": "Standard_D2",
                        "size": "Standard_D2 (Cores: 2, Memory: 7 GB) (eastus)",
                        "region": "westus",
                        "term": "P3Y",
                        "meterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "onDemandCount": 0,
                        "onDemandCost": 110.99038119400001,
                        "reservedCount": 0,
                        "reservedCost": 0,
                        "recommendedCount": 1,
                        "recommendedCost": 49.160529680364135,
                        "totalSavings": 61.82985151363587,
                        "totalSavingsPercent": 0.557073963063191
                      }
                    ],
                    "summary": {
                      "totalSavings": 61.82985151363587,
                      "currencyCode": "USD",
                      "totalSavingsPercent": 0.557073963063191,
                      "term": "",
                      "paymentOption": "",
                      "service": "compute",
                      "onDemandCount": 0,
                      "onDemandCost": 110.99038119400001,
                      "reservedCount": 0,
                      "reservedCost": 0,
                      "recommendedCount": 1,
                      "recommendedCost": 49.160529680364135
                    }
                  }
                }
              }
            }
          }
        },
        "summary": {
          "totalSavings": 34.51946338578294,
          "currencyCode": "USD",
          "totalSavingsPercent": 0.311013107752521,
          "term": "",
          "paymentOption": "",
          "service": "compute",
          "onDemandCount": 0,
          "onDemandCost": 110.99038119400001,
          "reservedCount": 0,
          "reservedCost": 0,
          "recommendedCount": 1,
          "recommendedCost": 76.47091780821707
        }
      }
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "max": 50,
    "offset": 0
  }
}

This endpoint retrieves discoveries. By default, only includes discoveries that have not been ignored or executed.

HTTP Request

GET $serverUrl/api/guidance

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Reference name, status message and action, restricts query to only load discoveries which contain the phrase specified
severity Severity level filter, restricts query to only load discoveries of specified severity level: info, low, warning, critical
type Discovery type filter, restricts query to only load discoveries of specified discover type. See discovery types
state Filter by state, restricts query to only load discoveries by state: any, processed, ignored

Get a Specific Discovery

curl "$serverUrl/api/guidance/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "discovery": {
    "id": 2,
    "dateCreated": "2020-03-18T17:36:09+0000",
    "lastUpdated": "2020-03-21T18:49:27+0000",
    "actionCategory": "power",
    "actionMessage": "Shutdown 10.30.21.76",
    "actionTitle": "shutdown",
    "actionType": "shutdown",
    "actionValue": "off",
    "actionValueType": "power",
    "actionPlanId": null,
    "statusMessage": "Utilization for virtual machine 10.30.21.76 suggests it is not in use",
    "accountId": 1,
    "userId": null,
    "siteId": null,
    "zone": {
      "id": 4,
      "name": "Denver VMware Virtual Center Cloud",
      "zoneType": {
        "id": 14,
        "name": "VMware vCenter"
      }
    },
    "state": "processed",
    "stateMessage": "shutdown resource",
    "severity": "info",
    "resolved": true,
    "resolvedMessage": null,
    "refType": "computeServer",
    "refId": 6,
    "refName": "10.30.21.76",
    "type": {
      "id": 1,
      "name": "Shutdown",
      "code": "shutdown",
      "title": "Shutdown resource"
    },
    "savings": {
      "amount": 40.0,
      "currency": "USD"
    },
    "resource": {
      "id": 6,
      "externalId": "host-58630",
      "internalId": null,
      "externalUniqueId": null,
      "accountId": 1,
      "account": {
        "name": "Stubby Toes Inc."
      },
      "name": "10.30.21.76",
      "visibility": "private",
      "description": null,
      "zoneId": 4,
      "siteId": 4,
      "resourcePoolId": 9,
      "folderId": null,
      "sshHost": null,
      "sshPort": 22,
      "externalIp": null,
      "internalIp": null,
      "volumeId": null,
      "platform": null,
      "platformVersion": null,
      "sshUsername": "xxxxx",
      "sshPassword": null,
      "osDevice": "/dev/sda",
      "osType": "esxi",
      "dataDevice": "/dev/sdb",
      "lvmEnabled": true,
      "apiKey": "xxxxx",
      "softwareRaid": false,
      "dateCreated": "2019-07-29T19:05:31+0000",
      "lastUpdated": "2020-02-26T07:10:59+0000",
      "stats": {
        "ts": "2020-02-26T07:10:59Z",
        "freeMemory": 94497890304,
        "maxMemory": 137402474496,
        "usedMemory": 42904584192,
        "maxStorage": 3000483446784,
        "usedStorage": 897040577986,
        "cpuUsage": 10.99583333
      },
      "status": "provisioned",
      "statusMessage": null,
      "errorMessage": null,
      "statusDate": "2019-07-29T19:05:31+0000",
      "statusPercent": null,
      "statusEta": null,
      "powerState": "on",
      "computeServerType": {
        "id": 157,
        "code": "vmwareHypervisor",
        "name": "vSphere Hypervisor",
        "managed": false,
        "externalDelete": false
      },
      "agentInstalled": false,
      "lastAgentUpdate": null,
      "agentVersion": null,
      "maxCores": 12,
      "maxMemory": 137402474496,
      "maxStorage": 3000483446784,
      "maxCpu": null,
      "serverOs": {
        "id": 53,
        "name": "esxi 6",
        "description": null,
        "vendor": "vmware",
        "category": "esxi",
        "osFamily": null,
        "osVersion": "6",
        "bitCount": 64,
        "platform": "esxi"
      },
      "enabled": true,
      "tagCompliant": null,
      "zone": {
        "id": 4,
        "name": "VMware Virtual Center Cloud"
      },
      "plan": {
        "id": null,
        "code": null,
        "name": null
      },
      "containers": [

      ]
    },
    "config": {
      "exists": true,
      "objectId": 6,
      "networkBandwidthCount": 0,
      "networkBandwidthMin": 0,
      "networkBandwidthMax": 0,
      "networkBandwidthAvg": 0,
      "networkBandwidthSum": 0,
      "netRxUsageCount": 5,
      "netRxUsageMin": 0,
      "netRxUsageMax": 185.0,
      "netRxUsageAvg": 108.2,
      "netRxUsageSum": 541.0,
      "cpuSystemTimeCount": 0,
      "cpuSystemTimeMin": 0,
      "cpuSystemTimeMax": 0,
      "cpuSystemTimeAvg": 0,
      "cpuSystemTimeSum": 0,
      "cpuTotalTimeCount": 0,
      "cpuTotalTimeMin": 0,
      "cpuTotalTimeMax": 0,
      "cpuTotalTimeAvg": 0,
      "cpuTotalTimeSum": 0,
      "cpuUsageCount": 0,
      "cpuUsageMin": 0,
      "cpuUsageMax": 0,
      "cpuUsageAvg": 0,
      "cpuUsageSum": 0,
      "netTxUsageCount": 5,
      "netTxUsageMin": 0,
      "netTxUsageMax": 244.0,
      "netTxUsageAvg": 156.4,
      "netTxUsageSum": 782.0,
      "cpuUserTimeCount": 0,
      "cpuUserTimeMin": 0,
      "cpuUserTimeMax": 0,
      "cpuUserTimeAvg": 0,
      "cpuUserTimeSum": 0,
      "cpuIdleTimeCount": 0,
      "cpuIdleTimeMin": 0,
      "cpuIdleTimeMax": 0,
      "cpuIdleTimeAvg": 0,
      "cpuIdleTimeSum": 0
    }
  }
}

This endpoint retrieves a specific discovery.

HTTP Request

GET $serverUrl/api/guidance/:id

URL Parameters

Parameter Description
id ID of the discovery

Get Guidance Stats

curl "$serverUrl/api/guidance/stats" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "stats": {
    "total": 14,
    "savings": {
      "amount": -165.98050103021708,
      "currency": "USD"
    },
    "severity": {
      "low": 0,
      "info": 14,
      "warning": 0,
      "critical": 0
    },
    "type": {
      "size": 13,
      "shutdown": 0,
      "move": 0,
      "schedule": 0
    }
  }
}

This endpoint retrieves a summary of actionable discoveries.

HTTP Request

GET $serverUrl/api/guidance/stats

Get Discovery Types

curl "$serverUrl/api/guidance/types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "types": [
    {
      "id": 1,
      "name": "Shutdown",
      "code": "shutdown",
      "category": "utilization",
      "title": "Shutdown resource"
    },
    {
      "id": 2,
      "name": "Sizing",
      "code": "size",
      "category": "utilization",
      "title": "Resize resource"
    },
    {
      "id": 3,
      "name": "Host Capacity",
      "code": "hostCapacity",
      "category": "utilization",
      "title": "Add Capacity"
    },
    {
      "id": 4,
      "name": "Host Balancing",
      "code": "hostBalancing",
      "category": "utilization",
      "title": "Balance Host"
    },
    {
      "id": 5,
      "name": "Datastore Capacity",
      "code": "datastoreCapacity",
      "category": "utilization",
      "title": "Add Capacity"
    },
    {
      "id": 6,
      "name": "Reservation Recommendation",
      "code": "reservations",
      "category": "utilization",
      "title": "Add Reservations"
    }
  ]
}

This endpoint retrieves a list of discovery types.

HTTP Request

GET $serverUrl/api/guidance/types

Execute a Discovery

Use this command to execute a discovery.

curl -XPUT "$serverUrl/api/guidance/1/execute" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" 

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/guidance/:id/execute

URL Parameters

Parameter Description
id The ID of the discovery

Ignore a Discovery

Use this command to ignore a discovery.

curl -XPUT "$serverUrl/api/guidance/1/ignore" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" 

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/guidance/:id/ignore

URL Parameters

Parameter Description
id The ID of the discovery

Provisioning

The Provisioning API endpoints provide management of Instances, Apps, Automation and Deployments.

Morpheus supports a diverse set of cloud APIS for provisioning compute and services. In order to facilitate some of these capabilities and preserve some of the diverse sets of feature sets across these plaforms it is necessary to provide a means to dynamicaly specifying provisioning options depending on what is being provisioned. Morpheus calls these ProvisionType. Each InstanceTypeLayout that can be provisioned has a correlating ProvisionType and each CloudType (aka ZoneType) has a list of supported provision types it is capable of provisioning. This record contains optionTypes (see section on optionTypes for specifics on how to parse this data) as well as information for building out network parameters and storage parameters by listing different storage type information.

Get All Provision Types

Fetch the list of available provision types.

curl "$serverUrl/api/provision-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
    "provisionTypes": [
        {
            "id": 9,
            "name": "Amazon",
            "description": null,
            "code": "amazon",
            "aclEnabled": false,
            "multiTenant": false,
            "managed": true,
            "hostNetwork": true,
            "customSupported": false,
            "mapPorts": false,
            "exportServer": null,
            "viewSet": "amazonCustom",
            "serverType": "ami",
            "hostType": "vm",
            "addVolumes": true,
            "hasDatastore": false,
            "hasNetworks": null,
            "maxNetworks": null,
            "customizeVolume": true,
            "rootDiskCustomizable": true,
            "lvmSupported": true,
            "hostDiskMode": "lvm",
            "minDisk": 0,
            "maxDisk": null,
            "resizeCopiesVolumes": true,
            "optionTypes": [
                {
                    "name": "subnet",
                    "description": null,
                    "fieldName": "subnetId",
                    "fieldLabel": "Subnet",
                    "fieldContext": "config",
                    "fieldAddOn": null,
                    "placeHolder": null,
                    "helpBlock": "",
                    "defaultValue": null,
                    "optionSource": "amazonSubnet",
                    "type": "select",
                    "advanced": false,
                    "required": true,
                    "editable": false,
                    "config": [],
                    "displayOrder": 100
                },
                {
                    "name": "security group",
                    "description": null,
                    "fieldName": "securityId",
                    "fieldLabel": "Security Group",
                    "fieldContext": "config",
                    "fieldAddOn": null,
                    "placeHolder": null,
                    "helpBlock": "",
                    "defaultValue": null,
                    "optionSource": "amazonSecurityGroup",
                    "type": "select",
                    "advanced": false,
                    "required": true,
                    "editable": false,
                    "config": [],
                    "displayOrder": 101
                },
                {
                    "name": "public key",
                    "description": null,
                    "fieldName": "publicKeyId",
                    "fieldLabel": "Public Key",
                    "fieldContext": "config",
                    "fieldAddOn": null,
                    "placeHolder": null,
                    "helpBlock": "",
                    "defaultValue": null,
                    "optionSource": "keyPairs",
                    "type": "select",
                    "advanced": false,
                    "required": false,
                    "editable": false,
                    "config": [],
                    "displayOrder": 9
                }
            ],
            "customOptionTypes": [],
            "networkTypes": [],
            "storageTypes": [
                {
                    "id": 7,
                    "code": "amazon-sc1",
                    "name": "sc1",
                    "displayOrder": 4,
                    "defaultType": false,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                },
                {
                    "id": 4,
                    "code": "amazon-io1",
                    "name": "io1",
                    "displayOrder": 2,
                    "defaultType": false,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                },
                {
                    "id": 5,
                    "code": "amazon-gp2",
                    "name": "gp2",
                    "displayOrder": 1,
                    "defaultType": true,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                },
                {
                    "id": 6,
                    "code": "amazon-st1",
                    "name": "st1",
                    "displayOrder": 3,
                    "defaultType": false,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                }
            ],
            "rootStorageTypes": [
                {
                    "id": 7,
                    "code": "amazon-sc1",
                    "name": "sc1",
                    "displayOrder": 4,
                    "defaultType": false,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                },
                {
                    "id": 4,
                    "code": "amazon-io1",
                    "name": "io1",
                    "displayOrder": 2,
                    "defaultType": false,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                },
                {
                    "id": 5,
                    "code": "amazon-gp2",
                    "name": "gp2",
                    "displayOrder": 1,
                    "defaultType": true,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                },
                {
                    "id": 6,
                    "code": "amazon-st1",
                    "name": "st1",
                    "displayOrder": 3,
                    "defaultType": false,
                    "customLabel": true,
                    "customSize": true,
                    "customSizeOptions": null
                }
            ],
            "controllerTypes": []
        }
    ]
}

HTTP Request

GET $serverUrl/api/provision-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name and code, restricts query to only load provision types which contain the phrase specified
name Name filter, restricts query to only load type matching name specified
code Code filter, restricts query to only load type matching code specified

Get Specific Provision Type

curl "$serverUrl/api/provision-types/9"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "success": true,
  "provisionType": {
        "id": 9,
        "name": "Amazon",
        "description": null,
        "code": "amazon",
        "aclEnabled": false,
        "multiTenant": false,
        "managed": true,
        "hostNetwork": true,
        "customSupported": false,
        "mapPorts": false,
        "exportServer": null,
        "viewSet": "amazonCustom",
        "serverType": "ami",
        "hostType": "vm",
        "addVolumes": true,
        "hasDatastore": false,
        "hasNetworks": null,
        "maxNetworks": null,
        "customizeVolume": true,
        "rootDiskCustomizable": true,
        "lvmSupported": true,
        "hostDiskMode": "lvm",
        "minDisk": 0,
        "maxDisk": null,
        "resizeCopiesVolumes": true,
        "optionTypes": [
            {
                "name": "subnet",
                "description": null,
                "fieldName": "subnetId",
                "fieldLabel": "Subnet",
                "fieldContext": "config",
                "fieldAddOn": null,
                "placeHolder": null,
                "helpBlock": "",
                "defaultValue": null,
                "optionSource": "amazonSubnet",
                "type": "select",
                "advanced": false,
                "required": true,
                "editable": false,
                "config": [],
                "displayOrder": 100
            },
            {
                "name": "security group",
                "description": null,
                "fieldName": "securityId",
                "fieldLabel": "Security Group",
                "fieldContext": "config",
                "fieldAddOn": null,
                "placeHolder": null,
                "helpBlock": "",
                "defaultValue": null,
                "optionSource": "amazonSecurityGroup",
                "type": "select",
                "advanced": false,
                "required": true,
                "editable": false,
                "config": [],
                "displayOrder": 101
            },
            {
                "name": "public key",
                "description": null,
                "fieldName": "publicKeyId",
                "fieldLabel": "Public Key",
                "fieldContext": "config",
                "fieldAddOn": null,
                "placeHolder": null,
                "helpBlock": "",
                "defaultValue": null,
                "optionSource": "keyPairs",
                "type": "select",
                "advanced": false,
                "required": false,
                "editable": false,
                "config": [],
                "displayOrder": 9
            }
        ],
        "customOptionTypes": [],
        "networkTypes": [],
        "storageTypes": [
            {
                "id": 7,
                "code": "amazon-sc1",
                "name": "sc1",
                "displayOrder": 4,
                "defaultType": false,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            },
            {
                "id": 4,
                "code": "amazon-io1",
                "name": "io1",
                "displayOrder": 2,
                "defaultType": false,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            },
            {
                "id": 5,
                "code": "amazon-gp2",
                "name": "gp2",
                "displayOrder": 1,
                "defaultType": true,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            },
            {
                "id": 6,
                "code": "amazon-st1",
                "name": "st1",
                "displayOrder": 3,
                "defaultType": false,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            }
        ],
        "rootStorageTypes": [
            {
                "id": 7,
                "code": "amazon-sc1",
                "name": "sc1",
                "displayOrder": 4,
                "defaultType": false,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            },
            {
                "id": 4,
                "code": "amazon-io1",
                "name": "io1",
                "displayOrder": 2,
                "defaultType": false,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            },
            {
                "id": 5,
                "code": "amazon-gp2",
                "name": "gp2",
                "displayOrder": 1,
                "defaultType": true,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            },
            {
                "id": 6,
                "code": "amazon-st1",
                "name": "st1",
                "displayOrder": 3,
                "defaultType": false,
                "customLabel": true,
                "customSize": true,
                "customSizeOptions": null
            }
        ],
        "controllerTypes": []
    }
}

HTTP Request

GET $serverUrl/api/provision-types/:id

Instances

Instances are sets of containers or vms (Morpheus API represents a vm as a container attached to a server) of various types that can be provisioned across the Morpheus stack and offer a wide range of services. MySQL, Redis, ElasticSearch, PostgreSQL, Tomcat, nginx, Confluence, Jenkins, and more. There are a few important concept differentiators between what Morpheus calls an instance and what amazon calls an instance. In Morpheus an isntance can represent many vms or containers that are of a set. For example. If you wanted to spin up a Mongo sharded replicaset, that requires 7 virtual machines or 7 docker containers. Morpheus represents this as a singular instance with a specified layout and then represents all the associated services running within that instance as containers. If, a container record is a docker container then the serverId it belongs to is representative of the Docker Host it was provisioned onto. If the container is a virtual machine then the serverId represents the compute resource it was provisioned onto, (i.e. the virtual machine).

Get All Instances

curl "$serverUrl/api/instances?max=3"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instances": [
    {
      "id": 1530,
      "accountId": 1,
      "instanceType": {
        "id": 35,
        "code": "ubuntu",
        "category": "os",
        "name": "Ubuntu"
      },
      "group": {
        "id": 3,
        "name": "Demo"
      },
      "cloud": {
        "id": 6,
        "name": "San Mateo VMware"
      },
      "containers": [
        1798
      ],
      "servers": [
        2
      ],
      "connectionInfo": [
        {
          "ip": "192.168.162.59",
          "port": 22
        }
      ],
      "layout": {
        "id": 105
      },
      "plan": {
        "id": 12,
        "code": "vm-2048"
      },
      "name": "ah-San Mateo VMware-ubuntu",
      "description": null,
      "instanceVersion": null,
      "dateCreated": "2017-01-31T21:30:49+0000",
      "lastUpdated": "2017-02-07T22:58:26+0000",
      "hostName": "ah-San-Mateo-VMware-ubuntu",
      "domainName": null,
      "environmentPrefix": null,
      "firewallEnabled": true,
      "networkLevel": "container",
      "autoScale": false,
      "instanceContext": "production",
      "currentDeployId": null,
      "status": "running",
      "statusMessage": null,
      "errorMessage": null,
      "statusDate": "2017-01-31T21:34:07+0000",
      "statusPercent": null,
      "statusEta": null,
      "userStatus": null,
      "createdBy": {
        "id": 38
      }
    },
    {
      "id": 1653,
      "accountId": 1,
      "instanceType": {
        "id": 35,
        "code": "ubuntu",
        "category": "os",
        "name": "Ubuntu"
      },
      "group": {
        "id": 3,
        "name": "Demo"
      },
      "cloud": {
        "id": 6,
        "name": "San Mateo VMware"
      },
      "containers": [
        1945
      ],
      "servers": [
        2
      ],
      "connectionInfo": [
        {
          "ip": "192.168.163.55",
          "port": 22
        }
      ],
      "layout": {
        "id": 105
      },
      "plan": {
        "id": 11,
        "code": "vm-1024"
      },
      "name": "ah-San Mateo VMware-ubuntu-PDNStest",
      "description": null,
      "instanceVersion": null,
      "dateCreated": "2017-02-10T14:27:42+0000",
      "lastUpdated": "2017-02-10T14:31:19+0000",
      "hostName": "ah-san-mateo-vmware-ubuntu-pdnstest",
      "domainName": null,
      "environmentPrefix": null,
      "firewallEnabled": true,
      "networkLevel": "container",
      "autoScale": false,
      "instanceContext": "dev",
      "currentDeployId": null,
      "status": "running",
      "statusMessage": null,
      "errorMessage": null,
      "statusDate": "2017-02-10T14:30:43+0000",
      "statusPercent": null,
      "statusEta": null,
      "userStatus": null,
      "createdBy": {
        "id": 38
      }
    },
    {
      "id": 1624,
      "accountId": 1,
      "instanceType": {
        "id": 21,
        "code": "apache",
        "category": "web",
        "name": "Apache"
      },
      "group": {
        "id": 163,
        "name": "snow-approvals"
      },
      "cloud": {
        "id": 6,
        "name": "San Mateo VMware"
      },
      "containers": [
        1912
      ],
      "servers": [
        3
      ],
      "connectionInfo": [
        {
          "ip": "192.168.163.28",
          "port": 10009
        }
      ],
      "layout": {
        "id": 48
      },
      "plan": {
        "id": 3,
        "code": "container-256"
      },
      "name": "approval-snow-test",
      "description": null,
      "instanceVersion": null,
      "dateCreated": "2017-02-09T06:45:30+0000",
      "lastUpdated": "2017-02-09T06:53:20+0000",
      "hostName": "approval-snow-test",
      "domainName": null,
      "environmentPrefix": null,
      "firewallEnabled": true,
      "networkLevel": "container",
      "autoScale": false,
      "instanceContext": null,
      "currentDeployId": null,
      "status": "running",
      "statusMessage": null,
      "errorMessage": null,
      "statusDate": "2017-02-09T06:53:20+0000",
      "statusPercent": null,
      "statusEta": null,
      "userStatus": null,
      "owner": {
        "id": 1,
        "username": "admin"
      }
    }
  ],
  "stats": {
    "1530": {
      "usedStorage": 6776664064,
      "maxStorage": 21067075584,
      "usedMemory": 1909739520,
      "maxMemory": 2098315264,
      "usedCpu": 1.0926682792
    },
    "1653": {
      "usedStorage": 2662801408,
      "maxStorage": 10499452928,
      "usedMemory": 935444480,
      "maxMemory": 1041350656,
      "usedCpu": 0.1501000667
    },
    "1624": {
      "usedStorage": 4829184,
      "maxStorage": 3103539200,
      "usedMemory": 9113600,
      "maxMemory": 268435456,
      "usedCpu": 0
    }
  },
  "loadBalancers": [],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 3,
    "total": 21
  }
}

This endpoint retrieves a paginated list of instances.

HTTP Request

GET $serverUrl/api/instances

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
name Filter by name
phrase Filter by wildcard search of name and description
instanceType Filter by instance type code
lastUpdated Date filter, restricts query to only load instances updated timestamp is more recent or equal to the date specified
createdBy Filter by Created By (User) ID. Accepts multiple values.
agentInstalled Filter instances by if agent is installed or not on the associated servers.
status Filter by instance status
environment Filter by environment code
showDeleted false If true, includes instances in pending removal status.
deleted If true, only instances in pending removal status are returned.
expireDate Filter by expireDate less than equal to specified date
expireDateMin Filter expireDate greater than or equal to the specified date
expireDays Filter by expireDays less than or equal to the specified value
expireDaysMin Filter by expireDays greater than or equal to the specified value
shutdownDate Filter by shutdownDate less than equal to the specified date
shutdownDateMin Filter by shutdownDate greater than or equal to the specified date
shutdownDays Filter by shutdownDays less than or equal to the specified value
shutdownDaysMin Filter by shutdownDays greater than or equal to the specified value
labels Filter by label(s).
tags Filter by tags (metadata). This allows filtering by arbitrary tag names and values like this tags.foo=bar.
metadata Alias for tags.
details false Include details=true to return more details about the instance, ie. containerDetails. Available in api version 5.2.8/5.3.2.

Get a Specific Instance

curl "$serverUrl/api/instances/1216" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instance": {
    "id": 392,
    "uuid": "6ccf1fa9-da1f-4318-841e-7bf30c4522c6",
    "accountId": 1,
    "tenant": {
      "id": 1,
      "name": "Morpheus Data"
    },
    "instanceType": {
      "id": 6,
      "code": "apache",
      "category": "web",
      "name": "Apache"
    },
    "group": {
      "id": 1,
      "name": "dev"
    },
    "cloud": {
      "id": 39,
      "name": "amazon"
    },
    "containers": [
      945
    ],
    "servers": [
      4002
    ],
    "connectionInfo": [
      {
        "ip": "10.100.1.8",
        "port": 80
      }
    ],
    "layout": {
      "id": 31,
      "name": "Amazon Apache on Ubuntu 14.04",
      "provisionTypeCode": "amazon"
    },
    "plan": {
      "id": 1,
      "code": "amazon-t2.nano",
      "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
    },
    "name": "sa-apache-1",
    "description": "new description",
    "environment": null,
    "config": {
      "createUser": true,
      "isEC2": false,
      "isVpcSelectable": true,
      "noAgent": null,
      "availabilityId": null,
      "securityId": null,
      "publicIpType": "subnet",
      "instanceProfile": null,
      "resourcePoolId": "173",
      "poolProviderType": null,
      "name": "${userInitials}-apache-${sequence}",
      "hostName": "${userInitials}-apache-${sequence}",
      "instanceType": {
        "code": null
      },
      "site": {
        "id": 1,
        "name": "dev"
      },
      "environmentPrefix": null,
      "layout": {
        "id": 31,
        "code": "apache-amazon-2.4-single"
      },
      "type": "apache",
      "memoryDisplay": "MB",
      "securityGroups": [
        {
          "id": "sg-21dd8144"
        }
      ],
      "customOptions": {
        "isPrimary": "on",
        "inventoryName": "DB12"
      },
      "createBackup": true,
      "backup": {
        "createBackup": true,
        "jobAction": "new",
        "jobRetentionCount": "3",
        "veeamManagedServer": "",
        "backupRepository": 1,
        "jobSchedule": 2,
        "target": 37006
      },
      "layoutSize": 1,
      "lbInstances": [

      ]
    },
    "configGroup": null,
    "configId": null,
    "configRole": null,
    "volumes": [
      {
        "controllerId": null,
        "datastoreId": null,
        "displayOrder": 0,
        "id": 177034,
        "maxIOPS": null,
        "maxStorage": 10737418240,
        "name": "root",
        "shortName": "root",
        "resizeable": true,
        "rootVolume": true,
        "size": 10,
        "storageType": 5,
        "unitNumber": null,
        "controllerMountPoint": null
      }
    ],
    "controllers": [

    ],
    "interfaces": [
      {
        "id": "365",
        "network": {
          "id": 365,
          "group": null,
          "subnet": null,
          "dhcpServer": true,
          "name": "labs1",
          "pool": null
        },
        "ipAddress": null,
        "networkInterfaceTypeId": null,
        "ipMode": ""
      }
    ],
    "customOptions": {
      "isPrimary": "on",
      "inventoryName": "DB12"
    },
    "instanceVersion": "2.4",
    "labels": [
      "foo",
      "bar"
    ],
    "tags": [
      {
        "id": 70539,
        "name": "Morpheus Id",
        "value": "945"
      },
      {
        "id": 70541,
        "name": "Morpheus Instance Id",
        "value": "392"
      },
      {
        "id": 70538,
        "name": "Morpheus Labels",
        "value": "foo,bar"
      },
      {
        "id": 70540,
        "name": "Morpheus Server Id",
        "value": "4002"
      },
      {
        "id": 70530,
        "name": "abc",
        "value": "123"
      }
    ],
    "evars": [
      {
        "name": "APACHE_IP",
        "value": "10.100.1.8",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_HOST",
        "value": "container945",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_HTTP",
        "value": 80,
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_80_TCP_PORT",
        "value": 80,
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_80_TCP_PROTO",
        "value": "tcp",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_80_TCP_ADDR",
        "value": "10.100.1.8",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_80_TCP",
        "value": "tcp://10.100.1.8:80",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_HTTPS",
        "value": 443,
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_443_TCP_PORT",
        "value": 443,
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_443_TCP_PROTO",
        "value": "tcp",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_443_TCP_ADDR",
        "value": "10.100.1.8",
        "export": true,
        "masked": false
      },
      {
        "name": "APACHE_PORT_443_TCP",
        "value": "tcp://10.100.1.8:443",
        "export": true,
        "masked": false
      }
    ],
    "maxMemory": 536870912,
    "maxStorage": 10737418240,
    "maxCores": 1,
    "coresPerSocket": 1,
    "maxCpu": 1,
    "hourlyCost": 0.0086816667,
    "hourlyPrice": 0.0086816667,
    "instancePrice": {
      "price": 6.2508,
      "cost": 6.2508,
      "currency": "USD",
      "unit": "month"
    },
    "dateCreated": "2020-11-02T16:36:32Z",
    "lastUpdated": "2021-06-21T21:00:01Z",
    "hostName": "sa-apache-1",
    "domainName": null,
    "environmentPrefix": null,
    "firewallEnabled": true,
    "networkLevel": "container",
    "autoScale": false,
    "instanceContext": null,
    "currentDeployId": null,
    "locked": false,
    "status": "running",
    "statusMessage": null,
    "errorMessage": null,
    "statusDate": "2020-11-02T16:38:12Z",
    "statusPercent": null,
    "statusEta": null,
    "userStatus": null,
    "expireDays": null,
    "renewDays": null,
    "expireCount": 0,
    "expireDate": null,
    "expireWarningDate": null,
    "expireWarningSent": false,
    "shutdownDays": null,
    "shutdownRenewDays": null,
    "shutdownCount": 0,
    "shutdownDate": null,
    "shutdownWarningDate": null,
    "shutdownWarningSent": false,
    "removalDate": null,
    "createdBy": {
      "id": 1,
      "username": "admin"
    },
    "owner": {
      "id": 1,
      "username": "admin"
    },
    "notes": null,
    "stats": {
      "usedStorage": 0,
      "maxStorage": 10737418240,
      "usedMemory": 233500000,
      "maxMemory": 500212000,
      "usedCpu": 0.0667445352,
      "cpuUsage": 0.0667445352,
      "cpuUsagePeak": 0.0667445352,
      "cpuUsageAvg": 0.0667445352
    },
    "powerSchedule": null,
    "isScalable": true,
    "instanceThreshold": null,
    "isBusy": false,
    "apps": [

    ],
    "currentLoadBalancerInstances": [

    ],
    "currentLoadBalancerContainersIn": 0,
    "currentLoadBalancerContainersOut": 0,
    "lastDeploy": null,
    "containerDetails": [
      {
        "id": 945,
        "uuid": "c19f7209-df3a-443c-93a8-ccefacb3783c",
        "name": "sa-apache-1_945",
        "ip": "10.100.1.8",
        "internalIp": "10.100.1.8",
        "internalHostname": "container945",
        "externalHostname": "sa-apache-1",
        "externalDomain": "localdomain",
        "externalFqdn": "sa-apache-1.localdomain",
        "accountId": 1,
        "instance": {
          "id": 392,
          "name": "sa-apache-1"
        },
        "containerType": {
          "id": 31,
          "code": "apache-amazon-2.4",
          "category": "apache",
          "name": "Apache 2.4"
        },
        "containerTypeSet": {
          "id": 31,
          "code": "apache-amazon-2.4-set",
          "category": "apache"
        },
        "server": {
          "id": 4002,
          "uuid": "fbf4234d-cd25-47b5-bdd1-49a9132d2871",
          "externalId": "i-033fbb2f1a9c2c225",
          "internalId": null,
          "externalUniqueId": null,
          "name": "sa-apache-1",
          "externalName": "sa-apache-1",
          "hostname": "sa-apache-1",
          "accountId": 1,
          "account": {
            "id": 1,
            "name": "Morpheus Data"
          },
          "owner": {
            "id": 1,
            "username": "admin"
          },
          "zone": {
            "id": 39,
            "name": "amazon"
          },
          "plan": {
            "id": 1,
            "code": "amazon-t2.nano",
            "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
          },
          "computeServerType": {
            "id": 45,
            "code": "amazonVm",
            "name": "Amazon Instance",
            "managed": true,
            "externalDelete": true
          },
          "visibility": "private",
          "description": null,
          "zoneId": 39,
          "siteId": 1,
          "resourcePoolId": 173,
          "folderId": null,
          "sshHost": null,
          "sshPort": 22,
          "externalIp": null,
          "internalIp": "10.100.1.8",
          "platform": "ubuntu",
          "platformVersion": "14.04",
          "dateCreated": "2020-11-02T16:36:32Z",
          "lastUpdated": "2021-06-22T18:06:32Z",
          "stats": {
            "ts": "2021-06-22T18:06:28+0000",
            "freeMemory": 266712000,
            "usedMemory": 233500000,
            "freeSwap": 0,
            "usedSwap": 0,
            "cpuIdleTime": 692815380,
            "cpuSystemTime": 224850,
            "cpuUserTime": 382640,
            "cpuTotalTime": 693422870,
            "cpuUsage": 0.06674528121948242,
            "maxStorage": 10737418240,
            "usedStorage": 1568661504,
            "reservedStorage": 10423046144,
            "netTxUsage": 27,
            "netRxUsage": 23,
            "networkBandwidth": 0
          },
          "status": "provisioned",
          "statusMessage": null,
          "errorMessage": null,
          "statusDate": "2020-11-02T16:36:50Z",
          "statusPercent": null,
          "statusEta": null,
          "powerState": "on",
          "agentInstalled": true,
          "lastAgentUpdate": "2021-06-22T18:06:32Z",
          "agentVersion": "2.0.0",
          "maxCores": 1,
          "coresPerSocket": 1,
          "maxMemory": 536870912,
          "maxStorage": 10737418240,
          "maxCpu": null,
          "hourlyCost": 0.0086816667,
          "hourlyPrice": 0.0086816667,
          "sourceImage": {
            "id": 22,
            "code": "amazon.ec2.image.morpheus.apache.2.4",
            "name": "ubuntu-14_04-apache-2_4-morph.0.1"
          },
          "serverOs": {
            "id": 5,
            "code": "ubuntu.14.04.64",
            "name": "ubuntu 14 64-bit",
            "description": null,
            "vendor": "canonical",
            "category": "ubuntu",
            "osFamily": "debian",
            "osVersion": "14.04",
            "bitCount": 64,
            "platform": "linux"
          },
          "volumes": [
            {
              "id": 177034,
              "name": "root",
              "controllerId": null,
              "controllerMountPoint": null,
              "resizeable": true,
              "rootVolume": true,
              "unitNumber": null,
              "typeId": 5,
              "configurableIOPS": false,
              "datastoreId": null,
              "maxStorage": 10737418240,
              "displayOrder": 0,
              "maxIOPS": null
            }
          ],
          "controllers": [

          ],
          "interfaces": [
            {
              "id": 297842,
              "refType": null,
              "refId": null,
              "name": "eth0",
              "internalId": null,
              "externalId": "eni-0689d61ea999db573",
              "uniqueId": "morpheus-nic-392-945-0",
              "publicIpAddress": null,
              "publicIpv6Address": null,
              "ipAddress": "10.100.1.8",
              "ipv6Address": null,
              "ipSubnet": null,
              "ipv6Subnet": null,
              "description": "",
              "dhcp": true,
              "active": true,
              "poolAssigned": false,
              "primaryInterface": true,
              "network": {
                "id": 365,
                "name": "labs1"
              },
              "subnet": null,
              "networkGroup": null,
              "networkPosition": null,
              "networkPool": null,
              "networkDomain": null,
              "type": {
                "id": 1,
                "code": "standard",
                "name": "standard"
              },
              "ipMode": "",
              "macAddress": "06:92:59:62:73:a3"
            }
          ],
          "labels": [

          ],
          "tags": [
            {
              "id": 70536,
              "name": "Morpheus Id",
              "value": "945"
            },
            {
              "id": 70535,
              "name": "Morpheus Instance Id",
              "value": "392"
            },
            {
              "id": 70537,
              "name": "Morpheus Labels",
              "value": "foo,bar"
            },
            {
              "id": 70534,
              "name": "Morpheus Server Id",
              "value": "4002"
            },
            {
              "id": 70531,
              "name": "abc",
              "value": "123"
            }
          ],
          "enabled": true,
          "tagCompliant": null
        },
        "cloud": {
          "id": 39,
          "name": "amazon"
        },
        "ports": [
          {
            "id": 192,
            "index": 0,
            "external": 80,
            "internal": 80,
            "displayName": "Http",
            "primaryPort": false,
            "export": true,
            "visible": true,
            "exportName": "HTTP",
            "loadBalanceProtocol": null,
            "loadBalance": true,
            "protocol": "http",
            "link": true,
            "externalIp": null,
            "internalIp": null
          },
          {
            "id": 193,
            "index": 1,
            "external": 443,
            "internal": 443,
            "displayName": "Https",
            "primaryPort": false,
            "export": true,
            "visible": true,
            "exportName": "HTTPS",
            "loadBalanceProtocol": null,
            "loadBalance": true,
            "protocol": "https",
            "link": true,
            "externalIp": null,
            "internalIp": null
          }
        ],
        "plan": {
          "id": 1,
          "code": "amazon-t2.nano",
          "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
        },
        "configGroup": null,
        "configId": null,
        "configRole": null,
        "dateCreated": "2020-11-02T16:36:32Z",
        "lastUpdated": "2021-06-22T18:06:32Z",
        "statsEnabled": true,
        "status": "running",
        "userStatus": "running",
        "environmentPrefix": null,
        "stats": {
          "ts": "2021-06-22T18:06:28+0000",
          "running": true,
          "userCpuUsage": 0.0333722676,
          "systemCpuUsage": 0.0333722676,
          "usedMemory": 233500000,
          "maxMemory": 500212000,
          "cacheMemory": 190968000,
          "maxStorage": null,
          "usedStorage": 0,
          "readIOPS": 0,
          "writeIOPS": 0.2333333333,
          "totalIOPS": 0.2333333333,
          "iops": {
          },
          "netTxUsage": 27,
          "netRxUsage": 23
        },
        "runtimeInfo": {
        },
        "containerVersion": null,
        "repositoryImage": null,
        "planCategory": null,
        "hostname": "sa-apache-1",
        "domainName": null,
        "volumeCreated": false,
        "containerCreated": true,
        "maxStorage": 10737418240,
        "maxMemory": 536870912,
        "maxCores": 1,
        "coresPerSocket": 1,
        "maxCpu": 1,
        "hourlyCost": 0.0086816667,
        "hourlyPrice": 0.0086816667
      }
    ]
  }
}

This endpoint retrieves a specific instance.

HTTP Request

GET $serverUrl/api/instances/:id

URL Parameters

Parameter Description
:id ID of the instance

Query Parameters

Parameter Default Description
details true More details about the instance are returned by default, ie. containerDetails. Available in api version 5.2.8/5.3.2.

Get Env Variables

curl "$serverUrl/api/instances/1216/envs" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "envs": [
    {
      "export": false,
      "masked": false,
      "name": "DATABASE_NAME",
      "value": "spud_marketing"
    }
  ],
  "readOnlyEnvs": {
    "TOMCAT_HOST": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_HOST",
      "value": "container1414"
    },
    "TOMCAT_HOST_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_HOST_2",
      "value": "container1759"
    },
    "TOMCAT_IP": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_IP",
      "value": "192.168.163.232"
    },
    "TOMCAT_IP_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_IP_2",
      "value": "192.168.163.233"
    },
    "TOMCAT_PORT": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT",
      "value": 10017
    },
    "TOMCAT_PORT_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_2",
      "value": 10017
    },
    "TOMCAT_PORT_8080_TCP": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP",
      "value": "tcp://192.168.163.232:10017"
    },
    "TOMCAT_PORT_8080_TCP_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_2",
      "value": "tcp://192.168.163.233:10017"
    },
    "TOMCAT_PORT_8080_TCP_ADDR": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_ADDR",
      "value": "192.168.163.232"
    },
    "TOMCAT_PORT_8080_TCP_ADDR_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_ADDR_2",
      "value": "192.168.163.233"
    },
    "TOMCAT_PORT_8080_TCP_PORT": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_PORT",
      "value": 10017
    },
    "TOMCAT_PORT_8080_TCP_PORT_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_PORT_2",
      "value": 10017
    },
    "TOMCAT_PORT_8080_TCP_PROTO": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_PROTO",
      "value": "tcp"
    },
    "TOMCAT_PORT_8080_TCP_PROTO_2": {
      "export": true,
      "masked": false,
      "name": "TOMCAT_PORT_8080_TCP_PROTO_2",
      "value": "tcp"
    }
  },
  "importedEnvs": {
    "MYSQL_HOST": {
      "export": true,
      "masked": false,
      "name": "MYSQL_HOST",
      "value": "container1413"
    },
    "MYSQL_HOST_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_HOST_2",
      "value": "container1756"
    },
    "MYSQL_IP": {
      "export": true,
      "masked": false,
      "name": "MYSQL_IP",
      "value": "192.168.163.232"
    },
    "MYSQL_IP_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_IP_2",
      "value": "192.168.163.233"
    },
    "MYSQL_MASTER": {
      "export": true,
      "masked": false,
      "name": "MYSQL_HOST",
      "value": "container1413"
    },
    "MYSQL_PASSWORD": {
      "export": true,
      "masked": true,
      "name": "MYSQL_PASSWORD",
      "value": "************"
    },
    "MYSQL_PASSWORD_2": {
      "export": true,
      "masked": true,
      "name": "MYSQL_PASSWORD",
      "value": "************"
    },
    "MYSQL_PORT": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT",
      "value": 10016
    },
    "MYSQL_PORT_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_2",
      "value": 10016
    },
    "MYSQL_PORT_3306_TCP": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP",
      "value": "tcp://192.168.163.232:10016"
    },
    "MYSQL_PORT_3306_TCP_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_2",
      "value": "tcp://192.168.163.233:10016"
    },
    "MYSQL_PORT_3306_TCP_ADDR": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_ADDR",
      "value": "192.168.163.232"
    },
    "MYSQL_PORT_3306_TCP_ADDR_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_ADDR_2",
      "value": "192.168.163.233"
    },
    "MYSQL_PORT_3306_TCP_PORT": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_PORT",
      "value": 10016
    },
    "MYSQL_PORT_3306_TCP_PORT_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_PORT_2",
      "value": 10016
    },
    "MYSQL_PORT_3306_TCP_PROTO": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_PROTO",
      "value": "tcp"
    },
    "MYSQL_PORT_3306_TCP_PROTO_2": {
      "export": true,
      "masked": false,
      "name": "MYSQL_PORT_3306_TCP_PROTO_2",
      "value": "tcp"
    },
    "MYSQL_USERNAME": "root",
    "MYSQL_USERNAME_2": "root"
  }
}

This gets all the environment variables associated with the instance.

HTTP Request

GET $serverUrl/api/instances/:id/envs

URL Parameters

Parameter Description
:id ID of the instance

Get Instance History

curl "$serverUrl/api/instances/238/history" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "processes": [
    {
      "id": 250,
      "accountId": 1,
      "uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
      "processType": {
        "code": "provision",
        "name": "provision"
      },
      "description": null,
      "subType": null,
      "subId": null,
      "zoneId": 34,
      "integrationId": null,
      "instanceId": 238,
      "containerId": 240,
      "serverId": 601,
      "containerName": "apachetest",
      "displayName": "apachetest",
      "timerCategory": "vmware",
      "timerSubCategory": "28",
      "status": "failed",
      "reason": null,
      "percent": 100.0,
      "statusEta": 348246,
      "message": null,
      "output": null,
      "error": null,
      "startDate": "2018-09-28T19:10:56+0000",
      "endDate": "2018-09-28T20:21:49+0000",
      "duration": 4253127,
      "dateCreated": "2018-09-28T19:10:56+0000",
      "lastUpdated": "2018-09-28T20:21:49+0000",
      "createdBy": {
        "username": "admin",
        "displayName": "Admin"
      },
      "updatedBy": {
        "username": "admin",
        "displayName": "Admin"
      },
      "events": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves the process history for a specific instance.

Alternatively, the Process History endpoint can be used to get the same information.

HTTP Request

GET $serverUrl/api/instances/:id/history

URL Parameters

Parameter Description
:id ID of the instance

Query Parameters

Parameter Default Description
phrase If specified will return a partial match on displayName, message or output
containerId Filter by container id(s)
serverId Filter by server id(s)
zoneId Filter by zone id(s)

Get Container Details

curl "$serverUrl/api/instances/1216/containers" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containers": [
    {
      "id": 292,
      "accountId": 1,
      "instance": {
        "id": 294,
        "name": "nginxtest"
      },
      "containerType": {
        "id": 187,
        "code": "nginx-vmware-1.9",
        "category": "nginx",
        "name": "NGINX 1.9"
      },
      "containerTypeSet": {
        "id": 193,
        "code": "nginx-vmware-1.9-set",
        "category": "nginx"
      },
      "server": {
        "id": 653,
        "name": "nginxtest"
      },
      "cloud": {
        "id": 34,
        "name": "myvmware"
      },
      "name": "nginxtest_292",
      "ip": "10.30.20.50",
      "internalIp": "10.30.20.50",
      "internalHostname": "container292",
      "externalHostname": "nginxtest",
      "externalDomain": "localdomain",
      "externalFqdn": "nginxtest.localdomain",
      "ports": [
        {
          "index": 0,
          "external": 80,
          "internal": 80,
          "primaryPort": true,
          "displayName": "Http",
          "export": true,
          "visible": true,
          "loadBalance": true,
          "link": true,
          "exportName": "HTTP",
          "protocol": "http",
          "code": "nginx.80"
        },
        {
          "index": 1,
          "external": 443,
          "internal": 443,
          "primaryPort": false,
          "displayName": "Https",
          "export": true,
          "visible": true,
          "loadBalance": true,
          "link": true,
          "exportName": "HTTPS",
          "protocol": "https",
          "code": "nginx.443"
        }
      ],
      "plan": {
        "id": 76,
        "code": "vm-1024",
        "name": "1 CPU, 1GB Memory"
      },
      "dateCreated": "2019-02-20T18:29:05+0000",
      "lastUpdated": "2019-02-27T21:07:35+0000",
      "statsEnabled": true,
      "status": "running",
      "userStatus": "running",
      "environmentPrefix": null,
      "stats": {
        "ts": "2019-02-27T21:07:31+0000",
        "running": true,
        "userCpuUsage": 0.1504010695,
        "systemCpuUsage": 0.1838235294,
        "usedMemory": 317256000,
        "maxMemory": 1017032000,
        "cacheMemory": 404236000,
        "maxStorage": 10499452928,
        "usedStorage": 3700285440,
        "readIOPS": 0,
        "writeIOPS": 0.35,
        "totalIOPS": 0.35,
        "iops": {
        },
        "netTxUsage": 114,
        "netRxUsage": 2198
      },
      "runtimeInfo": {
      },
      "containerVersion": null,
      "repositoryImage": null,
      "planCategory": null,
      "hostname": "nginxtest",
      "domainName": null,
      "volumeCreated": true,
      "containerCreated": false,
      "maxStorage": 10737418240,
      "maxMemory": 1073741824,
      "maxCores": 1,
      "coresPerSocket": 1,
      "maxCpu": 1,
      "availableActions": [
        {
          "code": "nginx-1.9-remove-node",
          "name": "Remove Nginx Node"
        }
      ]
    }
  ]
}

This can be valuable for evaluating the details of the compute server(s) running on an instance

HTTP Request

GET $serverUrl/api/instances/:id/containers

URL Parameters

Parameter Description
:id ID of the instance

Get All Instance Types for Provisioning

curl "$serverUrl/api/instance-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "instanceTypes": [
    {
      "id": 12,
      "name": "ActiveMQ",
      "code": "activemq",
      "category": "messaging",
      "active": true,
      "versions": [
        "5.11"
      ],
      "instanceTypeLayouts": [
        {
          "id": 14,
          "code": "activemq-5.11",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/}
        }
      ]
    },
    {
      "id": 13,
      "name": "Cassandra",
      "code": "cassandra",
      "category": "nosql",
      "active": true,
      "versions": [
        "2.1"
      ],
      "instanceTypeLayouts": [
        {
          "id": 15,
          "code": "cassandra-2.1-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 10,
      "name": "Confluence",
      "code": "confluence",
      "category": "utils",
      "active": true,
      "versions": [
        "5.7"
      ],
      "instanceTypeLayouts": [
        {
          "id": 12,
          "code": "confluence-5.7",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 5,
      "name": "Elastic Search",
      "code": "elasticsearch",
      "category": "nosql",
      "active": true,
      "versions": [
        "1.5"
      ],
      "instanceTypeLayouts": [
        {
          "id": 3,
          "code": "elasticsearch-1.5-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        },
        {
          "id": 4,
          "code": "elasticsearch-1.5-cluster",
          "name": "Cluster",
          "description": "This will provision two nodes, in multi master cluster",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 7,
      "name": "Jenkins",
      "code": "jenkins",
      "category": "utils",
      "active": true,
      "versions": [
        "1.596"
      ],
      "instanceTypeLayouts": [
        {
          "id": 8,
          "code": "jenkins-1.596",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 2,
      "name": "Memcached",
      "code": "memcached",
      "category": "cache",
      "active": true,
      "versions": [
        "1.4"
      ],
      "instanceTypeLayouts": [
        {
          "id": 11,
          "code": "memcached-1.4-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 4,
      "name": "Mongo",
      "code": "mongo",
      "category": "nosql",
      "active": true,
      "versions": [
        "3.0"
      ],
      "instanceTypeLayouts": [
        {
          "id": 16,
          "code": "mongo-3.0-rs",
          "name": "ReplicaSet",
          "description": "This will provision a 3 node replicaSet",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        },
        {
          "id": 6,
          "code": "mongo-3.0-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 3,
      "name": "MySQL",
      "code": "mysql",
      "category": "sql",
      "active": true,
      "versions": [
        "5.6"
      ],
      "instanceTypeLayouts": [
        {
          "id": 5,
          "code": "mysql-5.6-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 8,
      "name": "Nexus",
      "code": "nexus",
      "category": "utils",
      "active": true,
      "versions": [
        "2.11"
      ],
      "instanceTypeLayouts": [
        {
          "id": 9,
          "code": "nexus-2.11",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 14,
      "name": "Nginx",
      "code": "nginx",
      "category": "web",
      "active": true,
      "versions": [
        "1.9"
      ],
      "instanceTypeLayouts": [

      ]
    },
    {
      "id": 11,
      "name": "Postgres",
      "code": "postgres",
      "category": "sql",
      "active": true,
      "versions": [
        "9.4"
      ],
      "instanceTypeLayouts": [
        {
          "id": 13,
          "code": "postgres-9.4-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 9,
      "name": "RabbitMQ",
      "code": "rabbitmq",
      "category": "utils",
      "active": true,
      "versions": [
        "3.5"
      ],
      "instanceTypeLayouts": [
        {
          "id": 10,
          "code": "rabbitmq-3.5",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 1,
      "name": "Redis",
      "code": "redis",
      "category": "cache",
      "active": true,
      "versions": [
        "3.0"
      ],
      "instanceTypeLayouts": [
        {
          "id": 1,
          "code": "redis-3.0-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        },
        {
          "id": 2,
          "code": "redis-3.0-master-slave",
          "name": "Master\/Slave",
          "description": "This will provision 2 containers, one master and 1 slave.",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    },
    {
      "id": 6,
      "name": "Tomcat",
      "code": "tomcat",
      "category": "web",
      "active": true,
      "versions": [
        "7.0.62"
      ],
      "instanceTypeLayouts": [
        {
          "id": 7,
          "code": "tomcat-7.0.62-single",
          "name": "Single Process",
          "description": "This will provision a single process with no redundancy",
          "provisionType": { /* see provision types */ },
          "optionTypes": { /** see option types **/ }
        }
      ]
    }
  ]
}

Fetch the list of available instance types. These can vary in range from database containers, to web containers, to custom containers.

HTTP Request

GET $serverUrl/api/instance-types

Get Specific Instance Type for Provisioning

curl "$serverUrl/api/instance-types/12"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "success": true,
  "instanceType": {
    "id": 12,
    "name": "ActiveMQ",
    "code": "activemq",
    "category": "messaging",
    "active": true,
    "versions": [
      "5.11"
    ],
    "instanceTypeLayouts": [
      {
        "id": 14,
        "code": "activemq-5.11",
        "name": "Single Process",
        "description": "This will provision a single process with no redundancy",
        "provisionType": { /* see provision types */ },
        "optionTypes": { /** see option types **/ }
      }
    ]
  }
}

Fetch an instance type by ID.

HTTP Request

GET $serverUrl/api/instance-types/:id

URL Parameters

Parameter Description
:id ID of the instance type

Get Available Service Plans for an Instance

curl -XGET "$serverUrl/api/instances/service-plans?zoneId=1&layoutId=75" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "plans": [
    {
      "id": 75,
      "name": "1 CPU, 512MB Memory",
      "value": 75,
      "code": "vm-512",
      "maxStorage": 10737418240,
      "maxMemory": 536870912,
      "maxCpu": 1,
      "maxCores": 1,
      "customCpu": false,
      "customMaxMemory": false,
      "customMaxStorage": true,
      "customMaxDataStorage": true,
      "customCoresPerSocket": false,
      "coresPerSocket": 1,
      "storageTypes": [
        {
          "id": 1,
          "editable": false,
          "optionTypes": [

          ],
          "displayOrder": 1,
          "code": "standard",
          "volumeType": "disk",
          "minStorage": null,
          "deletable": false,
          "defaultType": true,
          "createDatastore": null,
          "resizable": false,
          "storageType": null,
          "allowSearch": true,
          "volumeOptionSource": null,
          "displayName": "Disk",
          "minIOPS": null,
          "maxIOPS": null,
          "hasDatastore": true,
          "customSize": true,
          "autoDelete": true,
          "name": "Standard",
          "configurableIOPS": false,
          "customLabel": true,
          "enabled": true,
          "description": "Standard",
          "volumeCategory": "disk",
          "externalId": null,
          "maxStorage": null
        }
      ],
      "rootStorageTypes": [
        {
          "id": 1,
          "editable": false,
          "optionTypes": [

          ],
          "displayOrder": 1,
          "code": "standard",
          "volumeType": "disk",
          "minStorage": null,
          "deletable": false,
          "defaultType": true,
          "createDatastore": null,
          "resizable": false,
          "storageType": null,
          "allowSearch": true,
          "volumeOptionSource": null,
          "displayName": "Disk",
          "minIOPS": null,
          "maxIOPS": null,
          "hasDatastore": true,
          "customSize": true,
          "autoDelete": true,
          "name": "Standard",
          "configurableIOPS": false,
          "customLabel": true,
          "enabled": true,
          "description": "Standard",
          "volumeCategory": "disk",
          "externalId": null,
          "maxStorage": null
        }
      ],
      "addVolumes": true,
      "customizeVolume": true,
      "rootDiskCustomizable": true,
      "noDisks": false,
      "hasDatastore": true,
      "minDisk": 0,
      "maxDisk": null,
      "lvmSupported": true,
      "datastores": {
        "cluster": [
          {
            "id": 54,
            "name": "demo-qnap - 4.3TB Free"
          }
        ],
        "store": [
          {
            "id": 50,
            "name": "datastore1 - 463.4GB Free"
          }
        ]
      },
      "supportsAutoDatastore": true,
      "autoOptions": [
        {
          "id": "autoCluster",
          "name": "Auto - Cluster"
        },
        {
          "id": "auto",
          "name": "Auto - Datastore"
        }
      ],
      "cpuOptions": [

      ],
      "coreOptions": [

      ],
      "memoryOptions": [

      ],
      "rootCustomSizeOptions": {
      },
      "customSizeOptions": {
      },
      "customCores": false,
      "maxDisks": null,
      "memorySizeType": "MB"
    }
  ]
}

This endpoint retrieves all the Service Plans available for the specified cloud and instance layout. The response includes details about the plans and their configuration options. It may be used to get the list of available plans when creating a new instance or resizing an existing instance.

HTTP Request

GET $serverUrl/api/instances/service-plans?zoneId=:zoneId&layoutId=:layoutId&siteId=:siteId

Query Parameters

Parameter Required Description
zoneId Y The ID of the Cloud
layoutId Y The ID of the Instance Layout
siteId N The ID of the Group

Create an Instance

curl -X POST "$serverUrl/api/instances" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "zoneId": 6,
  "instance": {
    "name": "api-testing2",
    "site": {
      "id": 3
    },
    "instanceType": {
      "code": "Ubuntu"
    },
    "layout": {
      "id": 105
    },
    "plan": {
      "id": 75
    }
  },
  "volumes": [
    {
      "id": -1,
      "rootVolume": true,
      "name": "root",
      "size": 10,
      "sizeId": null,
      "storageType": 1,
      "datastoreId": "autoCluster"
    },
    {
      "id": -1,
      "rootVolume": false,
      "name": "data",
      "size": 5,
      "sizeId": null,
      "storageType": 1,
      "datastoreId": "auto"
    }
  ],
  "servicePlanOptions": {
    "maxCores": 1,
    "coresPerSocket": 1,
    "maxMemory": 536870912
  },
  "networkInterfaces": [
    {
      "network": {
        "id": 5
      },
      "networkInterfaceTypeId": 4
    }
  ],
  "config": {
    "publicKeyId": 14,
    "vmwareResourcePoolId": "resgroup-56",
    "hostId": null,
    "vmwareUsr": "apiuser",
    "vmwarePwd": "password",
    "vmwareDomainName": null,
    "vmwareCustomSpec": null
  },
  "evars": [
    {"name": "MY_APP_VAR1", "value": "VALUE1"},
    {"name": "MY_APP_VAR2", "value": "VALUE2"}
  ],
  "labels": [
    "foo", "bar"
  ],
  "tags": [
    {"name": "hello", "value": "world"},
    {"name": "flash", "value": "bang"}
  ]
}'

The above command returns a similar JSON structure when submitting a GET request for a single instance

HTTP Request

POST $serverUrl/api/instances

JSON Parameters

Parameter Required Default Description
instance Y n/a Key for name, site, instanceType layout, and plan
instance.name Y Name of the instance to be created
instance.site.id Y The Group ID to provision the instance into
instance.instanceType.code Y The type of instance by code we want to fetch
instance.layout.id Y The layout id for the instance type that you want to provision. i.e. single process or cluster
instance.plan.id Y The id for the memory and storage option pre-configured within Morpheus. See Available Service Plans
zoneId Y The Cloud ID to provision the instance onto
evars N [] Environment Variables, an array of objects that have name and value.
copies N 1 Number of copies to provision
layoutSize N 1 Apply a multiply factor of containers/vms within the instance
servicePlanOptions N Map of custom options depending on selected service plan.
servicePlanOptions.maxCores N Core Count
servicePlanOptions.coresPerSocket N Cores Per Socket
servicePlanOptions.maxMemory N Memory in bytes For backwards compatability, values less than 1048576 are treated as being in MB and will be converted to bytes
securityGroups N Key for security group configuration. It should be passed as an array of objects containing the id of the security group to assign the instance to
volumes N Key for volume configuration, see Volumes
networkInterfaces N Key for network configuration, see Network Interfaces
config Y Key for specific type configuration, see Config
labels N Array of strings (keywords)
tags N Metadata tags, Array of objects having a name and value.
metadata N Alias for tags
ports N Array of port objects, see Exposed Ports
taskSetId N The Workflow ID to execute.
taskSetName N The Workflow Name to execute.

Volumes

The (optional) volumes parameter is for LV configuration, can create additional LVs at provision It should be passed as an array of Objects with the following attributes:

Parameter Required Default Description
id N -1 The id for the LV configuration being created
rootVolume N true If set to false then a non-root LV will be created
name Y root Name/type of the LV being created
size N [from service plan] Size of the LV to be created in GBs
sizeId N Can be used to select pre-existing LV choices from Morpheus
storageType N Identifier for LV type
datastoreId Y The ID of the specific datastore. Auto selection can be specified as auto or autoCluster (for clusters).

Network Interfaces

The networkInterfaces parameter is for network configuration.

The Options API /api/options/zoneNetworkOptions?zoneId=5&provisionTypeId=10 can be used to see which options are available.

It should be passed as an array of Objects with the following attributes:

Parameter Required Default Description
network.id Y n/a id of the network to be used. A network group can be specified instead by prefixing its ID with networkGroup-.
networkInterfaceTypeId Y n/a The id of type of the network interface.
ipAddress Y n/a The ip address. Not applicable when using DHCP or IP Pools.
id N n/a The interface id. Applicable when resizing and you want to identify an interface to update that already exists.

Exposed Ports

The ports parameter is for port configuration.

The layout may have default ports, which are defined in node types, that are always configured. This parameter will be for additional custom ports to be opened.

It should be passed as an array of Objects with the following attributes:

Parameter Required Default Description
port Y n/a port number. eg. 8080
name N n/a A name for the port eg. web
lb N The load balancer protocol. HTTP, HTTPS, or TCP. Default is none.

Config

The config parameter is for configuration options that are specific to each Provision Type. The Provision Types api can be used to see which options are available.

JSON Config Parameters for VMware
Parameter Required Default Description
publicKeyId N ID of a public key to add to the instance
resourcePoolId Y External ID of the resource group to use for instance
hostId N Specific host to deploy to if so desired
vmwareUsr N Additional user to provision to instance
vmwarePwd N Password for additional user
vmwareDomainName N Domain name to be given to instance
vmwareCustomSpec N Customization spec ID
JSON Config Parameters for Docker
Parameter Required Default Description
provisionServerId N Specific host to deploy to if so desired
resourcePoolId Y External ID of the resource group to use for instance
JSON Config Parameters for Kubernetes
Parameter Required Default Description
resourcePoolId Y ID of the resource group (kubernetes cluster) to use for instance

Metadata

This is specific to AWS Metadata tags. Name-Values pairs can be anything you like and are added to the instance JSON as an array of n-v pairs per the example to the right:

-d '{
  "zoneId": 6,
  "instance": {
    ...
  }
  ...
  "tags": [
    {
      "name": "SampleName",
      "value": "SampleValue"
    }
    {
      "name": "BusinessUnit",
      "value": "QualityAssurance"
    }
  ]
  ...
}

There can be additional properties to apply to the instance. For example mysql provisioning requires a set of initial credentials. You can get a list of what these input options are by fetching the instance-types list via the instance-types api and getting available layouts as well as the provision type option types associated with the layout. Currently these input options are available from the option-types map. These however, can be overridden in the event a config options map exists on the layout object within. NOTE: See the API Document on OptionTypes for figuring out how to build property maps from them.

Updating an Instance

curl -X PUT "$serverUrl/api/instances/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "instance": {
      "description": "my new redis",
        "addTags": [
          {"name": "hello", "value": "world"},
          {"name": "flash", "value": "bang"}
        ],
        "removeTags": [
          {"name": "oldTag"}
        ]
    },
    "config": {
      "customOptions": {
        "dbfoldername": "data"
      }
    }
  }'

The above command returns a similar JSON structure when submitting a GET request for a single instance

HTTP Request

PUT $serverUrl/api/instances/:id

URL Parameters

Parameter Description
:id ID of the instance

JSON Instance Parameters

Parameter Default Description
name Unique name scoped to your account for the instance
description Optional description field
instanceContext Environment
labels Array of strings (keywords)
tags Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified.
addTags Add or update value of Metadata tags, Array of objects having a name and value
removeTags Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed.
powerScheduleType Power Schedule ID
site.id Group ID
ownerId User ID, can be used to change instance owner.
config.customOptions Custom Option Type settings object containing name value pairs to be updated.

Stop an Instance

curl -X PUT "$serverUrl/api/instances/1/stop" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will stop all containers running within an instance.

HTTP Request

PUT $serverUrl/api/instances/:id/stop

URL Parameters

Parameter Description
:id ID of the instance

Start an Instance

curl -X PUT "$serverUrl/api/instances/1/start" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will start all containers running within an instance.

HTTP Request

PUT $serverUrl/api/instances/:id/start

URL Parameters

Parameter Description
:id ID of the instance

Restart an Instance

curl -X PUT "$serverUrl/api/instances/1/restart" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will restart all containers running within an instance. This includes rebuilding the environment variables and applying settings to the docker containers.

HTTP Request

PUT $serverUrl/api/instances/:id/restart

URL Parameters

Parameter Description
:id ID of the instance

Suspend an Instance

curl -X PUT "$serverUrl/api/instances/1/suspend" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will suspend all containers in the instance.

HTTP Request

PUT $serverUrl/api/instances/:id/suspend

URL Parameters

Parameter Description
:id ID of the instance

Eject an Instance

curl -X PUT "$serverUrl/api/instances/1/eject" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will eject any ISO media on all containers in the instance.

HTTP Request

PUT $serverUrl/api/instances/:id/eject

URL Parameters

Parameter Description
:id ID of the instance

Resize an Instance

curl -X PUT "$serverUrl/api/instances/1/resize" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instance": {
    "id": 1,
    "plan": {
      "id": 15
    }
  },
  "volumes": [
    {
      "id": "-1",
      "rootVolume": true,
      "name": "root",
      "size": 20,
      "sizeId": null,
      "storageType": null,
      "datastoreId": null
    }
  ],
  "deleteOriginalVolumes": true,
  "servicePlanOptions": {
    "maxCores": 1,
    "coresPerSocket": 1,
    "maxMemory": 536870912
  },
  "networkInterfaces": [
    {
      "id": 534,
      "name": "eth0",
      "network": {
        "id": "network-20"
      }
    },
    {
      "name": "eth1",
      "network": {
        "id": "network-20"
      }
    }
  ]
}'

The above command returns JSON structure like this:

{
  "success": true
}

It is possible to resize containers within an instance by increasing their memory plan or storage limit. This is done by assigning a new service plan to the container. This endpoint also allows for NIC reconfiguration by passing a new array of networkInterfaces.

HTTP Request

PUT $serverUrl/api/instances/:id/resize

URL Parameters

Parameter Description
:id ID of the instance

JSON Parameters

Parameter Required Default Description
instance.plan.id N null The map containing the id of the service plan you wish to apply to the containers in this instance
servicePlanOptions N Map of custom options depending on selected service plan.
servicePlanOptions.maxCores N Core Count
servicePlanOptions.coresPerSocket N Cores Per Socket
servicePlanOptions.maxMemory N Memory in bytes For backwards compatability, values less than 1048576 are treated as being in MB and will be converted to bytes
volumes no defaults to plan config Can be used to grow just the logical volume of the instance instead of choosing a plan, see Volumes.
deleteOriginalVolumes no false Delete the original volumes after resizing. (Amazon only)
networkInterfaces N Key for network configuration, see Network Interfaces. Include id to update an existing interface. The existing interfaces and their id can be retrieved with the hosts API.

Run Workflow on an Instance

curl -X PUT "$serverUrl/api/instances/1/workflow?workflowId=99" \
  -H "Authorization: BEARER $accessToken" \
  -d '{ "taskSet": {
    "customOptions": {"foo":"bar"}
    }}'

The above command returns JSON structure like this:

{
  "success": true
}

This will run a provisioning workflow on all containers in an instance.

For operational workflows, see Execute a Workflow.

HTTP Request

PUT $serverUrl/api/instances/:id/workflow

URL Parameters

Parameter Description
:id ID of the instance

Query Parameters

Parameter Description
workflowId ID of the workflow to execute
workflowName Name of the workflow to execute

JSON Parameters

Parameter Default Description
taskSet Object containing workflow configuration parameters
taskSet.customOptions Object containing any custom option type configuration parameters

Clone an Instance

curl -X PUT "$serverUrl/api/instances/1/clone" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Name",
    "group": {
      "id": 1
  }}'

The above command returns JSON structure like this:

{
  "success": true
}

One can easily clone an instance and all containers within that instance. The containers are backed up via the backup services and used as a snapshot to produce a clone of the instance. It is possible to clone this app instance into an entirely different availability zone.

HTTP Request

PUT $serverUrl/api/instances/:id/clone

URL Parameters

Parameter Description
:id ID of the instance

JSON Parameters

Parameter Default Description
group null the map containing the id of the server group you would like to clone into.
group null the map containing the id of the server group you would like to clone into.
name null A name for the new cloned instance. If none is specified the existing name will be duplicated with the ‘clone’ suffix added.

This endpoint also supports all of the same parameters as Create and Instance, so you can override any configuration options when provisioning the clone.

Backup an Instance

curl -X PUT "$serverUrl/api/instances/1773/backup" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure that looks like this:

{
    "success": true
}

HTTP Request

PUT $serverUrl/api/instances/:id/backup

URL Parameters

Parameter Description
:id ID of the instance

Get list of backups for an Instance

curl "$serverUrl/api/instances/1773/backups" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure that looks like this:

{
    "instance": {
      "id": 1773
    },
    "backups": [
    ]
}

HTTP Request

GET $serverUrl/api/instances/:id/backups

URL Parameters

Parameter Description
:id ID of the instance

Get list of snapshots for an Instance

curl "$serverUrl/api/instances/1773/snapshots" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure that looks like this:

{
    "snapshots": [
    ]
}

HTTP Request

GET $serverUrl/api/instances/:id/snapshots

URL Parameters

Parameter Description
:id ID of the instance

Get a Specific Snapshot

curl "$serverUrl/api/snapshots/1216" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "snapshot": {
        "id": 59,
        "name": "auto-apache-114-2022-01-14T12:57:17.981Z",
        "description": null,
        "externalId": "snapshot-56466",
        "status": "complete",
        "state": null,
        "snapshotType": "vm",
        "snapshotCreated": "2022-01-14T12:57:38Z",
        "zone": {
            "id": 2,
            "name": "ld-vmware"
        },
        "datastore": null,
        "parentSnapshot": null,
        "currentlyActive": true,
        "dateCreated": "2022-01-14T12:57:20Z"
    }
}

This endpoint retrieves a specific snapshot.

HTTP Request

GET $serverUrl/api/snapshots/:id

URL Parameters

Parameter Description
:id ID of the snapshot

Snapshot an Instance

curl -X PUT "$serverUrl/api/instances/1773/snapshot" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "snapshot": {
    "name": "snapshot-test",
    "description": "A snapshot created via the Morpheus api",
  }
}'

The above command returns JSON structure that looks like this:

{
    "success": true
}

This endpoint will create a snapshot of an instance. This is done asychronously, so the ID of the snapshot is not returned.

HTTP Request

PUT $serverUrl/api/instances/:id/snapshot

URL Parameters

Parameter Description
:id ID of the instance

JSON Snapshot Parameters

These parameters are passed under an object named snapshot.

Parameter Default Description
name “{serverName}.{timestamp}” Optional name for the snapshot being created.
description Optional description for the snapshot

Import Snapshot of an Instance

curl -X PUT "$serverUrl/api/instances/1/import-snapshot" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "storageProviderId": 1
  }'

The above command returns JSON structure like this:

{
  "success": true
}

It is possible to import a snapshot of an instance. This creates a Virtual Image of the instance as it currently exists.

HTTP Request

PUT $serverUrl/api/instances/:id/import-snapshot

URL Parameters

Parameter Description
:id ID of the instance

JSON Parameters

Parameter Default Description
storageProviderId null Optional storage provider to use.

Revert Instance to Snapshot

curl -X PUT "$serverUrl/api/instances/1/revert-snapshot/1835" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

It is possible to restore an Instance to a snapshot.

HTTP Request

PUT $serverUrl/api/instances/:id/revert-snapshot/:snapshotId

URL Parameters

Parameter Description
:id ID of the instance
:snapshotId ID of the snapshot

Delete Snapshot of Instance

curl -X DELETE "$serverUrl/api/snapshots/1835" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

Delete snapshot of instance.

HTTP Request

DELETE $serverUrl/api/snapshots/:id

URL Parameters

Parameter Description
:id ID of the snapshot

Delete All Snapshots of Instance Container

curl -X DELETE "$serverUrl/api/instances/54/delete-container-snapshots/403" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

Delete All Snapshots attached to Instance Container.

HTTP Request

DELETE $serverUrl/api/instances/:id/delete-container-snapshots/:containerId

URL Parameters

Parameter Description
:id ID of instance
:containerId ID of the instance container

Delete All Snapshots of Instance

curl -X DELETE "$serverUrl/api/instances/54/delete-all-snapshots" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

Delete All Snapshots attached to Instance.

HTTP Request

DELETE $serverUrl/api/instances/:id/delete-all-snapshots

URL Parameters

Parameter Description
:id ID of the instance

Create Linked Clone of Instance Snapshot

curl -X PUT "$serverUrl/api/instances/1/linked-clone/1835" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

It is possible to create a linked clone of an Instance Snapshot.

HTTP Request

PUT $serverUrl/api/instances/:id/linked-clone/:snapshotId

URL Parameters

Parameter Description
:id ID of the instance
:snapshotId ID of the snapshot

Clone to Image

curl -X PUT "$serverUrl/api/instances/1/clone-image" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "templateName": "Example Image", "zoneFolder": "group-v81" }'

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint allows creating an image template from an existing instance.

HTTP Request

PUT $serverUrl/api/instances/:id/clone-image

URL Parameters

Parameter Description
:id ID of the instance

JSON Parameters

Parameter Default Description
templateName Image Template Name. Default is server name + timestamp.
zoneFolder Zone Folder externalId. This is required for VMware

Lock an Instance

curl -X PUT "$serverUrl/api/instances/1/lock" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will lock the instance. While locked, instances may not be removed.

HTTP Request

PUT $serverUrl/api/instances/:id/lock

URL Parameters

Parameter Description
:id ID of the instance

Unlock an Instance

curl -X PUT "$serverUrl/api/instances/1/unlock" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will unlock the instance.

HTTP Request

PUT $serverUrl/api/instances/:id/unlock

URL Parameters

Parameter Description
:id ID of the instance

Get Security Groups

curl -XGET "$serverUrl/api/instances/1/security-groups" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true,
  "firewallEnabled": true,
  "securityGroups": [
    {
      "id": 19,
      "accountId": 1,
      "name": "All Tomcat Access",
      "description": "Allow everyone to access Tomcat"
    }
  ]
}

This returns a list of all of the security groups applied to an instance and whether the firewall is enabled.

HTTP Request

GET $serverUrl/api/instances/:id/security-groups

URL Parameters

Parameter Description
:id ID of the instance

Set Security Groups

curl -X POST "$serverUrl/api/instances/1/security-groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "securityGroupIds": [19, 2] }'

The above command returns JSON structure similar to the 'get’ of security groups.

HTTP Request

POST $serverUrl/api/instances/:id/security-groups

URL Parameters

Parameter Description
:id ID of the instance

JSON Parameters

Parameter Default Description
securityGroupIds List of all security groups ids which should be applied. If no security groups should apply, pass ’[]’

This defines the list of all the security groups applied to an instance.

Delete an Instance

curl -XDELETE "$serverUrl/api/instances/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete an instance and all associated monitors and backups.

HTTP Request

DELETE $serverUrl/api/instances/:id

URL Parameters

Parameter Description
:id ID of the instance

Query Parameters

Parameter Default Description
preserveVolumes off Preserve Volumes
keepBackups off Preserve copy of backups
releaseEIPs on Release EIPs
force off Force Delete

Cancel Expiration of an Instance

curl -XPUT "$serverUrl/api/instances/2/cancel-expiration" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

This operation will cancel the expiration of an instance.

HTTP Request

PUT $serverUrl/api/instances/:id/cancel-expiration

URL Parameters

Parameter Description
:id ID of the instance

Extend Expiration of an Instance

curl -XPUT "$serverUrl/api/instances/2/extend-expiration" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

This operation will extend the expiration of an instance. The period of time it is extended is equal to the number of renewal days in the expiration policy.

HTTP Request

PUT $serverUrl/api/instances/:id/extend-expiration

URL Parameters

Parameter Description
:id ID of the instance

Cancel Shutdown of an Instance

curl -XPUT "$serverUrl/api/instances/2/cancel-shutdown" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

This operation will cancel the shutdown of an instance.

HTTP Request

PUT $serverUrl/api/instances/:id/cancel-shutdown

URL Parameters

Parameter Description
:id ID of the instance

Extend Shutdown of an Instance

curl -XPUT "$serverUrl/api/instances/2/extend-shutdown" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structure like this:

{
  "success": true
}

This operation will extend the shutdown of an instance. The period of time it is extended is equal to the number of renewal days in the expiration policy.

HTTP Request

PUT $serverUrl/api/instances/:id/extend-shutdown

URL Parameters

Parameter Description
:id ID of the instance

Cancel Removal of an Instance

curl -XPUT "$serverUrl/api/instances/2/cancel-removal" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structured like getting a single instance.

This operation will undo the delete of an instance that is pending removal.

HTTP Request

PUT $serverUrl/api/instances/:id/cancel-removal

URL Parameters

Parameter Description
:id ID of the instance

Apps

Apps are groupings of instances that are linked together to form a full application stack. They can be created with existing templates or new templates, as well as from existing instances.

Get All Apps

curl "$serverUrl/api/apps" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "apps": [
    {
      "id": 1,
      "name": "My Test App",
      "description": "Sample Description",
      "accountId": 1,
      "account": {
        "id": 1,
        "name": "root"
      },
      "owner": {
        "id": 127,
        "username": "admin"
      },
      "siteId": 1,
      "group": {
        "id": 1,
        "name": "My Group"
      },
      "blueprint": {
        "id": 135,
        "name": "Grails Example",
        "type": "morpheus"
      },
      "type": "morpheus",
      "status": "running",
      "instanceCount": 2,
      "containerCount": 2,
      "dateCreated": "2015-06-09T20:59:17Z",
      "lastUpdated": "2015-06-09T21:00:19Z",
      "appTiers": [
        {
          "tier": {
            "id": 2,
            "name": "App"
          },
          "appInstances": [
            {
              "instance": {
                "id": 53,
                "name": "Test App - Grails"
              }
            }
          ]
        },
        {
          "tier": {
            "id": 5,
            "name": "Database"
          },
          "appInstances": [
            {
              "instance": {
                "id": 54,
                "name": "Test App - MySQL"
              }
            }
          ]
        }
      ],
      "stats": {
        "usedMemory": 0,
        "maxMemory": 1073741824,
        "usedStorage": 0,
        "maxStorage": 21474836480,
        "running": 0,
        "total": 0,
        "cpuUsage": 0,
        "instanceCount": 2
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves a paginated list of apps.

HTTP Request

GET $serverUrl/api/apps

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
name Filter by name
phrase Filter by wildcard search of name and description
createdBy Filter by Created By (User) ID. Accepts multiple values.
showDeleted false If true, includes apps in pending removal status.

Get a Specific App

curl "$serverUrl/api/apps/4" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "app": {
    "id": 1,
    "name": "My Test App",
    "description": "Sample Description",
    "accountId": 1,
    "account": {
      "id": 1,
      "name": "root"
    },
    "owner": {
      "id": 127,
      "username": "admin"
    },
    "siteId": 1,
    "group": {
      "id": 1,
      "name": "My Group"
    },
    "blueprint": {
      "id": 135,
      "name": "Grails Example",
      "type": "morpheus"
    },
    "type": "morpheus",
    "status": "running",
    "instanceCount": 2,
    "containerCount": 2,
    "dateCreated": "2015-06-09T20:59:17Z",
    "lastUpdated": "2015-06-09T21:00:19Z",
    "appTiers": [
      {
        "tier": {
          "id": 2,
          "name": "App"
        },
        "appInstances": [
          {
            "instance": {
              "id": 53,
              "name": "Test App - Grails"
            }
          }
        ]
      },
      {
        "tier": {
          "id": 5,
          "name": "Database"
        },
        "appInstances": [
          {
            "instance": {
              "id": 54,
              "name": "Test App - MySQL"
            }
          }
        ]
      }
    ],
    "stats": {
      "usedMemory": 0,
      "maxMemory": 1073741824,
      "usedStorage": 0,
      "maxStorage": 21474836480,
      "running": 0,
      "total": 0,
      "cpuUsage": 0,
      "instanceCount": 2
    }
  }
}

This endpoint retrieves a specific app.

HTTP Request

GET $serverUrl/api/apps/:id

URL Parameters

Parameter Description
:id ID of the app

Create an App

curl -XPOST "$serverUrl/api/apps" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "blueprintId": "existing",
    "name": "sample",
    "description": "A sample app",
    "group": {
      "id": 1
    }
  }'

The above command returns JSON structured like getting a single app.

HTTP Request

POST $serverUrl/api/apps

JSON App Parameters

Parameter Default Description
blueprintId The ID of the Blueprint. Use existing to create a blank app.
name A unique name for the app
group A Map containing the id of the Group
description Description
environment Environment code (appContext)

Updating an App

curl -XPUT "$serverUrl/api/apps/2" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Sample App",
    "description": "A new description of this app",
  }'

The above command returns JSON structured like getting a single app.

This endpoint provides updating of some basic app settings.

HTTP Request

PUT $serverUrl/api/apps/:id

URL Parameters

Parameter Description
:id ID of the app

JSON App Parameters

Parameter Default Description
name Name
description Description
environment Environment (appContext)
ownerId User ID, can be used to change app owner. This also changes the owner for each instance in the app.

Add Existing Instance to App

curl -XPOST "$serverUrl/api/apps/1/add-instance" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"instanceId": 55, tierName: "App"}'

The above command returns JSON structured like getting a single app.

HTTP Request

POST $serverUrl/api/apps/:id/add-instance

URL Parameters

Parameter Description
:id ID of the app

JSON Parameters

Parameter Default Description
instanceId The ID of the instance being added
tierName The Name of the Tier

Remove Instance from App

curl -XPOST "$serverUrl/api/apps/1/remove-instance" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"instanceId": 55}'

The above command returns JSON structured like getting a single app.

HTTP Request

POST $serverUrl/api/apps/:id/remove-instance

URL Parameters

Parameter Description
:id ID of the app

JSON Parameters

Parameter Default Description
instanceId The ID of the instance being removed

Get Security Groups

curl -XGET "$serverUrl/api/apps/1/security-groups" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true,
  "firewallEnabled": true,
  "securityGroups": [
    {
      "id": 19,
      "accountId": 1,
      "name": "All Tomcat Access",
      "description": "Allow everyone to access Tomcat"
    }
  ]
}

This returns a list of all of the security groups applied to an app and whether the firewall is enabled.

HTTP Request

GET $serverUrl/api/apps/:id/security-groups

URL Parameters

Parameter Description
:id ID of the app

Set Security Groups

curl -XPOST "$serverUrl/api/apps/1/security-groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "securityGroupIds": [19, 2] }'

The above command returns JSON structure similar to the ‘get’ of security groups.

HTTP Request

POST $serverUrl/api/apps/:id/security-groups

URL Parameters

Parameter Description
:id ID of the app

JSON Parameters

Parameter Default Description
securityGroupIds List of all security groups ids which should be applied. If no security groups should apply, pass ’[]’

Delete an App

curl -XDELETE "$serverUrl/api/apps/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete an app. Use removeInstances=on to also delete the instances in the app and all associated monitors and backups.

HTTP Request

DELETE $serverUrl/api/apps/:id

URL Parameters

Parameter Description
:id ID of the app

Query Parameters

Parameter Default Description
removeInstances off Remove Instances
preserveVolumes off Preserve Volumes
keepBackups off Preserve copy of backups
releaseEIPs on Release EIPs
force off Force Delete

Undo Delete of an App

curl -XPUT "$serverUrl/api/apps/2/cancel-removal" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON structured like getting a single app.

This operation will undo the delete of an app that is pending removal.

HTTP Request

PUT $serverUrl/api/apps/:id/cancel-removal

URL Parameters

Parameter Description
:id ID of the app

Refresh State of an App

curl -XPOST "$serverUrl/api/apps/:id/refresh" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint provides a way to refresh the state of an app. This action only applies to Terraform, CloudFormation and ARM.

HTTP Request

POST $serverUrl/api/apps/:id/refresh

URL Parameters

Parameter Description
:id ID of the app

Apply State of an App

curl -XPOST "$serverUrl/api/apps/:id/apply" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint provides a way to apply the state of an app. This action only applies to Terraform, CloudFormation and ARM.

HTTP Request

POST $serverUrl/api/apps/:id/apply

URL Parameters

Parameter Description
:id ID of the app

Blueprints

Blueprints are templates for creating apps. They are a set of instance configurations, organized by tier, and scoped by group, cloud and environment.

A Blueprint may also be referred to as a App Template or appTemplate.

Get All Blueprints

curl "$serverUrl/api/blueprints" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "blueprints": [
    {
      "id": 135,
      "name": "test",
      "type": "morpheus",
      "description": null,
      "category": null,
      "config": {
        "image": "/assets/apps/template.png",
        "tiers": {
          "Web": {
            "linkedTiers": [

            ],
            "tierIndex": 1,
            "instances": [
              {
                "instance": {
                  "type": "nginx"
                },
                "groups": {
                  "My Group": {
                    "clouds": {
                      "My Cloud": {
                        "instance": {
                          "layout": {
                            "code": "nginx-vmware-1.9-single",
                            "id": 179
                          },
                          "name": "test-nginx-${sequence}",
                          "allowExisting": false,
                          "createUser": "on",
                          "type": "nginx",
                          "userGroup": {
                            "id": ""
                          }
                        },
                        "networkInterfaces": [
                          {
                            "ipMode": "",
                            "primaryInterface": true,
                            "network": {
                              "id": "",
                              "hasPool": false
                            },
                            "networkInterfaceTypeId": 4,
                            "networkInterfaceTypeIdName": "VMXNET 3"
                          }
                        ],
                        "volumes": [
                          {
                            "vId": 255,
                            "controllerMountPoint": "46:0:4:0",
                            "size": 10,
                            "maxIOPS": null,
                            "name": "root",
                            "rootVolume": true,
                            "storageType": 1,
                            "datastoreId": "autoCluster",
                            "maxStorage": 0
                          }
                        ],
                        "config": {
                          "resourcePoolId": "resgroup-123",
                          "createUser": true
                        },
                        "plan": {
                          "code": "vm-1024",
                          "id": 76
                        }
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        "name": "test",
        "templateImage": "",
        "type": "morpheus",
        "config": {
          "isVpcSelectable": true,
          "isEC2": false
        }
      },
      "visibility": "private",
      "resourcePermission": {
        "all": true,
        "sites": [

        ]
      },
      "owner": {
        "id": 1,
        "username": "admin"
      },
      "tenant": {
        "id": 1,
        "name": "root"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": "1",
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all blueprints.

HTTP Request

GET $serverUrl/api/blueprints

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
name Filter by name
phrase Filter by wildcard search of name and description

Get a Specific Blueprint

curl "$serverUrl/api/blueprints/4" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "blueprint": {
    "id": 135,
    "name": "test",
    "type": "morpheus",
    "description": null,
    "category": null,
    "config": {
      "image": "/assets/apps/template.png",
      "tiers": {
        "Web": {
          "linkedTiers": [

          ],
          "tierIndex": 1,
          "instances": [
            {
              "instance": {
                "type": "nginx"
              },
              "groups": {
                "My Group": {
                  "clouds": {
                    "My Cloud": {
                      "instance": {
                        "layout": {
                          "code": "nginx-vmware-1.9-single",
                          "id": 179
                        },
                        "name": "test-nginx-${sequence}",
                        "allowExisting": false,
                        "createUser": "on",
                        "type": "nginx",
                        "userGroup": {
                          "id": ""
                        }
                      },
                      "networkInterfaces": [
                        {
                          "ipMode": "",
                          "primaryInterface": true,
                          "network": {
                            "id": "",
                            "hasPool": false
                          },
                          "networkInterfaceTypeId": 4,
                          "networkInterfaceTypeIdName": "VMXNET 3"
                        }
                      ],
                      "volumes": [
                        {
                          "vId": 255,
                          "controllerMountPoint": "46:0:4:0",
                          "size": 10,
                          "maxIOPS": null,
                          "name": "root",
                          "rootVolume": true,
                          "storageType": 1,
                          "datastoreId": "autoCluster",
                          "maxStorage": 0
                        }
                      ],
                      "config": {
                        "resourcePoolId": "resgroup-123",
                        "createUser": true
                      },
                      "plan": {
                        "code": "vm-1024",
                        "id": 76
                      }
                    }
                  }
                }
              }
            }
          ]
        }
      },
      "name": "test",
      "templateImage": "",
      "type": "morpheus",
      "config": {
        "isVpcSelectable": true,
        "isEC2": false
      }
    },
    "visibility": "private",
    "resourcePermission": {
      "all": true,
      "sites": [

      ]
    },
    "owner": {
        "id": 1,
        "username": "admin"
      },
      "tenant": {
        "id": 1,
        "name": "root"
      }
  }
}

This endpoint retrieves a specific blueprint.

HTTP Request

GET $serverUrl/api/blueprints/:id

Create a Blueprint

curl -XPOST "$serverUrl/api/blueprints" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sample",
    "description": "A sample blueprint",
    "type": "morpheus",
    "tiers": {
      "Web": {
        "linkedTiers": [

        ],
        "tierIndex": 1,
        "instances": [
          {
            "instance": {
              "type": "nginx"
            },
            "groups": {
              "My Group": {
                "clouds": {
                  "My Cloud": {
                    "instance": {
                      "layout": {
                        "code": "nginx-vmware-1.9-single",
                        "id": 179
                      },
                      "name": "test-nginx-${sequence}",
                      "allowExisting": false,
                      "createUser": "on",
                      "type": "nginx",
                      "userGroup": {
                        "id": ""
                      }
                    },
                    "networkInterfaces": [
                      {
                        "ipMode": "",
                        "primaryInterface": true,
                        "network": {
                          "id": "",
                          "hasPool": false
                        },
                        "networkInterfaceTypeId": 4,
                        "networkInterfaceTypeIdName": "VMXNET 3"
                      }
                    ],
                    "volumes": [
                      {
                        "vId": 255,
                        "controllerMountPoint": "46:0:4:0",
                        "size": 10,
                        "maxIOPS": null,
                        "name": "root",
                        "rootVolume": true,
                        "storageType": 1,
                        "datastoreId": "autoCluster",
                        "maxStorage": 0
                      }
                    ],
                    "config": {
                      "resourcePoolId": "resgroup-123",
                      "createUser": true
                    },
                    "plan": {
                      "code": "vm-1024",
                      "id": 76
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  }'

The above command returns JSON structured like getting a single blueprint.

HTTP Request

POST $serverUrl/api/blueprints

JSON Blueprint Parameters

Parameter Default Description
name A name for the blueprint
description Optional description field
category morpheus Optional category field
type morpheus Blueprint Type. The default is ‘morpheus’.
tiers A Map containing a key for each tier and all their instances.

Blueprint Tiers Configuration

The blueprint tiers can be structured so that instance configurations are scoped to a specific environment, group and/or cloud. The environments key is the environment name. The groups key is the group name. The clouds key is the cloud name. The order of scoping must always be done in the order: environments, groups, and then clouds.

Updating a Blueprint

curl -XPUT "$serverUrl/api/blueprints/2" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sample",
    "description": "A sample nginx blueprint",
    "type": "morpheus",
    "tiers": {
      "Web": {
        "linkedTiers": [

        ],
        "tierIndex": 1,
        "instances": [
          {
            "instance": {
              "type": "nginx"
            },
            "groups": {
              "My Group": {
                "clouds": {
                  "My Cloud": {
                    "instance": {
                      "layout": {
                        "code": "nginx-vmware-1.9-single",
                        "id": 179
                      },
                      "name": "test-nginx-${sequence}",
                      "allowExisting": false,
                      "createUser": "on",
                      "type": "nginx",
                      "userGroup": {
                        "id": ""
                      }
                    },
                    "networkInterfaces": [
                      {
                        "ipMode": "",
                        "primaryInterface": true,
                        "network": {
                          "id": "",
                          "hasPool": false
                        },
                        "networkInterfaceTypeId": 4,
                        "networkInterfaceTypeIdName": "VMXNET 3"
                      }
                    ],
                    "volumes": [
                      {
                        "vId": 255,
                        "controllerMountPoint": "46:0:4:0",
                        "size": 10,
                        "maxIOPS": null,
                        "name": "root",
                        "rootVolume": true,
                        "storageType": 1,
                        "datastoreId": "autoCluster",
                        "maxStorage": 0
                      }
                    ],
                    "config": {
                      "resourcePoolId": "resgroup-123",
                      "createUser": true
                    },
                    "plan": {
                      "code": "vm-1024",
                      "id": 76
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  }'

The above command returns JSON structured like getting a single blueprint.

HTTP Request

PUT $serverUrl/api/blueprints/:id

JSON Blueprint Parameters

Same as Create.

This overwrites the entire config, so the entire blueprint config should be passed.

Update Blueprint Permissions

curl -XPOST "$serverUrl/api/blueprints/1/update-permissions" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "resourcePermission": {
    "all":false,
    "sites": [
      {"id": 1}
    ],
    "ownerId": 1
  }}'

The above command returns JSON structured like getting a single blueprint.

HTTP Request

POST $serverUrl/api/blueprints/:id/update-permissions

JSON Parameters

Parameter Default Description
resourcePermission.all Enable access for all groups
resourcePermission.sites Enable access for specific groups only
ownerId User ID, can be used to change blueprint owner.

Update Blueprint Image

curl -XPOST "$serverUrl/api/blueprints/1/image" \
  -H "Authorization: BEARER $accessToken"
  -F 'templateImage=@filename'

The above command returns JSON structured like getting a single blueprint.

HTTP Request

POST $serverUrl/api/blueprints/:id/image

Parameters

Parameter Default Description
templateImage Image File png,jpg,svg

Upload a new logo image. Expects multipart form data as the request format, not JSON.

Delete a Blueprint

curl -XDELETE "$serverUrl/api/blueprints/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/blueprints/:id

Jobs

Provides API interfaces for managing jobs within Morpheus.

Get All Jobs

curl "$serverUrl/api/jobs" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "jobs": [
    {
      "id": 5,
      "name": "task 2",
      "type": {
        "id": 3,
        "name": "Task Job",
        "code": "morpheus.task"
      },
      "task": {
        "id": 2
      },
      "jobSummary": "echo hello",
      "scheduleMode": "manual",
      "status": null,
      "namespace": null,
      "category": null,
      "description": null,
      "enabled": true,
      "dateCreated": "2019-11-13T19:17:50+0000",
      "lastUpdated": "2019-11-13T19:17:50+0000",
      "lastRun": null,
      "lastResult": null,
      "createdBy": {
        "id": 1,
        "username": "root"
      },
      "targetType": "server",
      "targets": [
        {
          "id": 8,
          "name": "server 1",
          "targetType": "server",
          "refId": 20
        }
      ],
      "customConfig": null,
      "customOptions": {"hello":"world"}
    }
  ],
  "stats": {
    "jobCount": 17,
    "todayCount": 7,
    "execCount": 17,
    "execSuccess": 0,
    "execSuccessRate": 0,
    "execFailed": 7,
    "execFailedRate": 41.17647059,
    "executionsPerDay": [
      0,
      1,
      1,
      3,
      2,
      3,
      7
    ]
  },
  "meta": {
    "size": 1,
    "total": 1,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all jobs.

HTTP Request

GET $serverUrl/api/jobs

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name or external ID filter, restricts query to only load jobs which contain the phrase specified
itemSource Source filter, restricts query to only load jobs of specified source: [all, user, sync]

Get a Specific Job

curl "$serverUrl/api/jobs/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "job": {
    "id": 14,
    "name": "Task 1",
    "type": {
      "id": 3,
      "name": "Task Job",
      "code": "morpheus.task"
    },
    "task": {
      "id": 1
    },
    "jobSummary": "echo hello",
    "scheduleMode": "1",
    "status": null,
    "namespace": null,
    "category": null,
    "description": null,
    "enabled": true,
    "dateCreated": "2019-11-16T18:29:35+0000",
    "lastUpdated": "2019-11-16T19:46:36+0000",
    "lastRun": "2019-11-16T19:45:20+0000",
    "lastResult": "error",
    "createdBy": {
      "id": 1,
      "username": "root"
    },
    "targetType": "server",
    "targets": [
      {
        "id": 35,
        "name": "Server 1",
        "targetType": "server",
        "refId": 55
      }
    ],
    "customConfig": null,
    "customOptions": {"hello":"world"}
  },
  "executions": {
    "jobExecutions": [
      {
        "id": 25,
        "name": "Task 1",
        "process": {
          "id": 181,
          "accountId": 1,
          "uniqueId": "6d1388d0-2482-429a-81e5-92afad192c5c",
          "processType": {
            "code": "serverWorkflow",
            "name": "workflow"
          },
          "description": "Task 1",
          "subType": null,
          "subId": null,
          "zoneId": 3,
          "integrationId": null,
          "instanceId": null,
          "containerId": null,
          "serverId": 55,
          "containerName": null,
          "displayName": "Server 1",
          "timerCategory": "Task 1",
          "timerSubCategory": "99",
          "status": "failed",
          "reason": null,
          "percent": 100.0,
          "statusEta": 180000,
          "message": "unknown error",
          "output": null,
          "error": null,
          "startDate": "2019-11-16T19:45:20+0000",
          "endDate": "2019-11-16T19:46:35+0000",
          "duration": 75585,
          "dateCreated": "2019-11-16T19:45:20+0000",
          "lastUpdated": "2019-11-16T19:46:36+0000",
          "createdBy": {
            "username": "root",
            "displayName": "Stubby Toes"
          },
          "updatedBy": {
            "username": "root",
            "displayName": "Stubby Toes"
          },
          "events": [
            {
              "id": 23,
              "processId": 166,
              "accountId": 1,
              "uniqueId": "8401ac1f-fc02-475d-a3ec-f61ea49e668b",
              "processType": {
                "code": "executeTask",
                "name": "execute task"
              },
              "description": "echo hello",
              "refType": "instance",
              "refId": 3,
              "subType": null,
              "subId": null,
              "zoneId": null,
              "integrationId": null,
              "instanceId": 3,
              "containerId": null,
              "serverId": null,
              "containerName": null,
              "displayName": "name",
              "status": "failed",
              "reason": null,
              "percent": 100.0,
              "statusEta": 180000,
              "message": "Task Execution Failed on Attempt 1\n",
              "output": null,
              "error": "Task Execution Failed on Attempt 1\n",
              "startDate": "2019-11-14T08:00:14+0000",
              "endDate": "2019-11-14T08:00:16+0000",
              "duration": 1800,
              "dateCreated": "2019-11-14T08:00:14+0000",
              "lastUpdated": "2019-11-14T08:00:16+0000",
              "createdBy": {
                "username": "root",
                "displayName": "Stubby Toes"
              },
              "updatedBy": {
                "username": "root",
                "displayName": "Stubby Toes"
              }
            }
          ]
        },
        "job": {
          "id": 14,
          "name": "Task 1",
          "description": null,
          "type": {
            "id": 3,
            "code": "morpheus.task",
            "name": "Task Job"
          }
        },
        "description": null,
        "dateCreated": "2019-11-16T19:45:20+0000",
        "startDate": "2019-11-16T19:45:20+0000",
        "endData": "2019-11-16T19:46:36+0000",
        "duration": 75513,
        "resultData": "{\"data\":{\"results\":[],\"processId\":181},\"errorCode\":null,\"errors\":{},\"inProgress\":false,\"msg\":\"\",\"success\":false}",
        "status": "error",
        "statusMessage": null
      }
    ],
    "meta": {
      "size": 1,
      "total": 1,
      "max": 25,
      "offset": 0
    }
  }
}

This endpoint retrieves a specific job.

HTTP Request

GET $serverUrl/api/jobs/:id

URL Parameters

Parameter Description
id ID of the job
includeExecCount Number of most recent job executions to include in response

Create a Job

Use this command to create a job. This command requires either a task task.id or workflow workflow.id (not both).

curl -XPOST "$serverUrl/api/jobs" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"job": {
        "name": "Job 1",
        "workflow": {
          "id": 3
        },
        "targetType": "server",
        "targets": [
          {
            "refId": 2
          },
          {
            "refId": 3
          }
        ],
        "scheduleMode": "manual",
        "customOptions":{"dbVersion":"5.7"}
     }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/jobs

JSON Parameters

Parameter Required Description
name Y Job name
enabled N Use this to set enabled state, defaults to true
task.id Y if workflow.id not used Use this to assign task to job. Not compatible with workflow
workflow.id Y if task.id not used Use this to assign workflow to job. Not compatible with task
targetType Y Target type where job will execute: appliance, instance, server
targets 1..n for instance or server target types Key for targets configuration, see Targets
scheduleMode Y Job execution schedule type ID or 'manual’ or 'dateTime’
customOptions Map of options to be used as values in the workflow tasks. These correspond to option types.
customConfig N Job custom configuration (String in JSON format)
dateTime N Date and Time to execute the job. Use UTC time in the format 2020-02-15T05:00:00Z. Required when scheduleMode is 'dateTime’.
run N If true executes job

Targets

The targets parameter is list of targets where job will execute.

Parameter Required Description
refId Y ID for instance or server depending on target type

Update a Job

curl -XPUT "$serverUrl/api/jobs/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"job": {
        "name": "Job 1",
        "workflow": {
          "id": 3
        },
        "targetType": "server",
        "targets": [
          {
            "refId": 2
          },
          {
            "refId": 3
          }
        ],
        "scheduleMode": "manual",
        "customOptions":{"hello":"world"},
        "customConfig": "{\"foo\":\"bar\"}",
        "run": true
     }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/jobs/:id

URL Parameters

Parameter Description
id ID of the job

JSON Parameters

Parameter Required Description
name N Job name
enabled N Use this to set enabled state
task.id N Use this to assign task to job. Not compatible with workflow
workflow.id N Use this to assign workflow to job. Not compatible with task
targetType N Target type where job will execute: appliance, instance, server
targets N Key for targets configuration, see Targets
scheduleMode Y Job execution schedule type ID or 'manual’ or 'dateTime’
customOptions Map of options to be used as values in the workflow tasks. These correspond to option types.
customConfig N Job custom configuration (String in JSON format)
dateTime N Date and Time to execute the job. Use UTC time in the format 2020-02-15T05:00:00Z. Required when scheduleMode is 'dateTime’.
run N If true executes job

Execute a Job

Use this command to execute a job.

curl -XPUT "$serverUrl/api/jobs/3/execute" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/jobs/:id/execute?customConfig=%7Bfoo%3Abar%7D

URL Parameters

Parameter Description
id ID of the job
customConfig Optional custom config

Delete a Job

Use this command to delete a job.

curl -XDELETE "$serverUrl/api/jobs/3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/jobs/:id

URL Parameters

Parameter Description
id ID of the job

Get Job Executions

curl "$serverUrl/api/job-executions" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "jobExecutions": [
    {
      "id": 30,
      "name": "name",
      "process": {
        "id": 190,
        "accountId": 1,
        "uniqueId": "2d959a94-0db6-427d-94b0-440737e9a485",
        "processType": {
          "code": "serverWorkflow",
          "name": "workflow"
        },
        "description": "name",
        "subType": null,
        "subId": null,
        "zoneId": 3,
        "integrationId": null,
        "instanceId": null,
        "containerId": null,
        "serverId": 21,
        "containerName": null,
        "displayName": "cluster resource name-master",
        "timerCategory": "name",
        "timerSubCategory": "191",
        "status": "failed",
        "reason": null,
        "percent": 100.0,
        "statusEta": 180000,
        "message": "unknown error",
        "output": null,
        "error": null,
        "startDate": "2019-11-17T14:27:08+0000",
        "endDate": "2019-11-17T14:28:23+0000",
        "duration": 75584,
        "dateCreated": "2019-11-17T14:27:08+0000",
        "lastUpdated": "2019-11-17T14:28:23+0000",
        "createdBy": {
          "username": "root",
          "displayName": "Stubby Toes"
        },
        "updatedBy": {
          "username": "root",
          "displayName": "Stubby Toes"
        },
        "events": [

        ]
      },
      "job": {
        "id": 3,
        "name": "name",
        "description": null,
        "type": {
          "id": 2,
          "code": "morpheus.workflow",
          "name": "Workflow Job"
        }
      },
      "description": null,
      "dateCreated": "2019-11-17T14:25:52+0000",
      "startDate": "2019-11-17T14:25:52+0000",
      "endData": "2019-11-17T14:28:23+0000",
      "duration": 151421,
      "resultData": "{\"data\":{\"results\":[],\"processId\":190},\"errorCode\":null,\"errors\":{},\"inProgress\":false,\"msg\":\"\",\"success\":false}",
      "status": "error",
      "statusMessage": null
    }
  ],
  "meta": {
    "size": 1,
    "total": 29,
    "max": "1",
    "offset": 0
  }
}

This endpoint retrieves job executions.

HTTP Request

GET $serverUrl/api/job-executions

Query Parameters

Parameter Default Description
jobId Job ID filter, restricts query to only load executions for specified job
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Name or external ID filter, restricts query to only load job executions which contain the phrase specified

Get a Specific Job Execution

curl "$serverUrl/api/job-executions/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "jobExecution": {
    "id": 26,
    "name": "Task 1",
    "process": {
      "id": 187,
      "accountId": 1,
      "uniqueId": "9872270f-1a0f-4c5e-9ae8-8afb692da0fa",
      "processType": {
        "code": "serverWorkflow",
        "name": "workflow"
      },
      "description": "Task 1",
      "subType": null,
      "subId": null,
      "zoneId": 3,
      "integrationId": null,
      "instanceId": null,
      "containerId": null,
      "serverId": 55,
      "containerName": null,
      "displayName": "docker1",
      "timerCategory": "Task 1",
      "timerSubCategory": "99",
      "status": "failed",
      "reason": null,
      "percent": 100.0,
      "statusEta": 180000,
      "message": "unknown error",
      "output": null,
      "error": null,
      "startDate": "2019-11-17T08:41:48+0000",
      "endDate": "2019-11-17T08:43:42+0000",
      "duration": 113862,
      "dateCreated": "2019-11-17T08:41:48+0000",
      "lastUpdated": "2019-11-17T08:43:42+0000",
      "createdBy": {
        "username": "root",
        "displayName": "Stubby Toes"
      },
      "updatedBy": {
        "username": "root",
        "displayName": "Stubby Toes"
      },
      "events": [

      ]
    },
    "job": {
      "id": 14,
      "name": "Task 1",
      "description": null,
      "type": {
        "id": 3,
        "code": "morpheus.task",
        "name": "Task Job"
      }
    },
    "description": null,
    "dateCreated": "2019-11-17T08:41:47+0000",
    "startDate": "2019-11-17T08:41:47+0000",
    "endData": "2019-11-17T08:43:42+0000",
    "duration": 115226,
    "resultData": "{\"data\":{\"results\":[],\"processId\":187},\"errorCode\":null,\"errors\":{},\"inProgress\":false,\"msg\":\"\",\"success\":false}",
    "status": "error",
    "statusMessage": null
  }
}

This endpoint retrieves a specific job execution.

HTTP Request

GET $serverUrl/api/job-executions/:id

URL Parameters

Parameter Description
id ID of the job execution

Get a Specific Job Execution Event

curl "$serverUrl/api/job-executions/1/events/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "processEvent": {
    "id": 32,
    "processId": 201,
    "accountId": 1,
    "uniqueId": "82368308-045e-40c8-ad41-faf7ecd6320e",
    "processType": {
      "code": "executeTask",
      "name": "execute task"
    },
    "description": "echo goodbye",
    "refType": "instance",
    "refId": 3,
    "subType": null,
    "subId": null,
    "zoneId": null,
    "integrationId": null,
    "instanceId": 3,
    "containerId": null,
    "serverId": null,
    "containerName": null,
    "displayName": "echo goodbye",
    "status": "failed",
    "reason": null,
    "percent": 100.0,
    "statusEta": 10568,
    "message": "Task Execution Failed on Attempt 1\n",
    "output": null,
    "error": "Task Execution Failed on Attempt 1\n",
    "startDate": "2019-11-19T08:00:25+0000",
    "endDate": "2019-11-19T08:00:27+0000",
    "duration": 1712,
    "dateCreated": "2019-11-19T08:00:25+0000",
    "lastUpdated": "2019-11-19T08:00:27+0000",
    "createdBy": {
      "username": "root",
      "displayName": "Stubby Toes"
    },
    "updatedBy": {
      "username": "root",
      "displayName": "Stubby Toes"
    }
  }
}

This endpoint retrieves a specific job execution event.

HTTP Request

GET $serverUrl/api/job-executions/:id/events/:eventId

URL Parameters

Parameter Description
id ID of the job execution
eventId ID of the job execution event

Automation

The Automation API endpoints provide the management of Tasks, Workflows, Executions, Scale Thresholds, Power and Execute Scheduling.

Tasks

Provides API interfaces for managing the creation and modification of automation tasks. Tasks are used in workflows for automation.

curl "$serverUrl/api/tasks"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "tasks": [
     {
      "id": 5,
      "accountId": 1,
      "name": "aptitude upgrade",
      "taskType": {
        "id": 1,
        "code": "script",
        "name": "Shell Script"
      },
      "file": {
        "id": 1275,
        "sourceType": "local",
        "contentRef": null,
        "contentPath": null,
        "repository": null,
        "content": "apt-get upgrade -y"
      },
      "taskOptions": {
      }
    },
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all tasks.

HTTP Request

GET $serverUrl/api/tasks

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by matching name
name Filter by name
taskTypeCodes Filter by task type code(s).

Get a Specific Task

curl "$serverUrl/api/tasks/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "task": {
      "id": 5,
      "accountId": 1,
      "name": "aptitude upgrade",
      "taskType": {
        "id": 1,
        "code": "script",
        "name": "Shell Script"
      },
      "file": {
        "id": 1275,
        "sourceType": "local",
        "contentRef": null,
        "contentPath": null,
        "repository": null,
        "content": "apt-get upgrade -y"
      },
      "taskOptions": {
      }
    }
}

This endpoint will retrieve a specific task by id

HTTP Request

GET $serverUrl/api/tasks/:id

URL Parameters

Parameter Description
ID The ID of the task

Create a Task

curl -XPOST "$serverUrl/api/tasks" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"task": {
    "name": "cleanup tmp files",
    "taskType": {
      "code": "script"
    },
    "executeTarget": "resource",
    "file": {
      "sourceType": "local",
      "content": "rm -rf /var/www/app1/tmp/*\nrm -rf /var/www/app2/tmp/*"
    }
  }}'

The above command returns JSON structured like getting a single task:

HTTP Request

POST $serverUrl/api/tasks

JSON Parameters

Parameter Default Description
name A unique name for the task
code A unique code for the task
taskType.code The type of task
taskOptions Map of options specific to each type. eg. script
resultType The result type eg. value, exitCode, keyValue, json
executeTarget The execution target. eg. local,remote,resource. The default value varies by task type.
retryable false If the task should be retried or not.
retryCount The number of times to retry.
retryDelaySeconds The delay, between retries.
file File, object specifying type and content, see File Object. This is required for task types that expect a script, having scriptable:true and an optionType of type:"file-content".

File Object Parameter

Parameter Required Description
sourceType Y File Source i.e. local, repository, url. Default is local.
content Y File content, the script text. Only required when sourceType is local.
contentPath Y Content Path, the repo file location or url. Required when sourceType is repository or url.
contentRef N Content Ref, the branch/tag. Only used when sourceType is repo.
repository.id N Code Repository ID, required for type repository. Use /api/options/codeRepositories to see available repositories.

JSON Parameters for Execute Target: Local

Parameter Default Description
taskOptions.localScriptGitId The Git Repo ID
taskOptions.localScriptGitRef The Git Repo Ref eg. master

These additional task options are available when using executeTarget of local.

JSON Parameters for Execute Target: Remote

Parameter Default Description
taskOptions.host Host or IP Address for remote execution
taskOptions.port 22 Port for remote execution
taskOptions.username Username for remote execution
taskOptions.password Password for remote execution

These additional task options are available when using executeTarget of remote.

Updating a Task

curl -XPUT "$serverUrl/api/tasks/5" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"task":{
    "name": "my task",
  }}'

The above command returns JSON structured like getting a single task:

HTTP Request

PUT $serverUrl/api/tasks/:id

URL Parameters

Parameter Description
ID The ID of the task

JSON Parameters

Same as Create.

Delete a Task

curl -XDELETE "$serverUrl/api/tasks/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/tasks/:id

URL Parameters

Parameter Description
ID The ID of the task

If a task is still tied to workflows, the delete will fail.

Execute a Task

curl -XPOST "$serverUrl/api/tasks/5/execute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"job":{
    "targetType": "instance",
    "instances": [1]
  }}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint executes a task on the specified instances or servers. Tasks are executed asynchronously, so to see the process and event results you may fetch the job execution record. See Get a Specific Job Execution.

HTTP Request

POST $serverUrl/api/tasks/:id/execute

URL Parameters

Parameter Description
ID The ID of the task

JSON Parameters

The following parameters are passed inside an object named job.

Parameter Default Description
name (task name) A name for the execution job. Can be used to find execution results with /api/processes?name=.
targetType The target context for task execution. Pass instance, server or appliance (None, execute locally on the appliance itself). This is required for tasks with executeTarget set to resource.
instances Array of Instance IDs. Only applicable for targetType is instance.
servers Array of Server IDs. Only applicable for targetType is server`.
customOptions Map of options to be used as values in the task. These correspond to option types.
customConfig String of custom configuration values as JSON.

Task Types

A Task Type is a type of automation task. Each type defines its own set of options to be configured for each task.

curl "$serverUrl/api/task-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "taskTypes": [
    {
      "id": 1,
      "code": "script",
      "name": "Shell Script",
      "category": "script",
      "description": null,
      "optionTypes": [
        {
          "id": 254,
          "name": "Script",
          "code": "script",
          "description": null,
          "fieldName": "script",
          "fieldLabel": "Script",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "code-editor",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 5,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        }
      ]
    },
    {
      "id": 2,
      "code": "sshTask",
      "name": "SSH Script",
      "category": "script",
      "description": null,
      "optionTypes": [
        {
          "id": 258,
          "name": "Key",
          "code": "sshKey",
          "description": null,
          "fieldName": "sshKey",
          "fieldLabel": "Key",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": "keyPairs",
          "type": "select",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 2,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        },
        {
          "id": 254,
          "name": "Script",
          "code": "script",
          "description": null,
          "fieldName": "script",
          "fieldLabel": "Script",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "code-editor",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 5,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        },
        {
          "id": 259,
          "name": "IP Address",
          "code": "host",
          "description": null,
          "fieldName": "host",
          "fieldLabel": "IP Address",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 0,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        },
        {
          "id": 257,
          "name": "Password",
          "code": "password",
          "description": null,
          "fieldName": "password",
          "fieldLabel": "Password",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "password",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 4,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        },
        {
          "id": 260,
          "name": "Port",
          "code": "port",
          "description": null,
          "fieldName": "port",
          "fieldLabel": "Port",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 1,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        },
        {
          "id": 256,
          "name": "Username",
          "code": "username",
          "description": null,
          "fieldName": "username",
          "fieldLabel": "Username",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 3,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        }
      ]
    }
  ]
}

HTTP Request

GET $serverUrl/api/task-types

Query Parameters

Parameter Default Description
name If specified will return an exact match on name or code
code If specified will return an exact match on code

Get a Specific Task Type

curl "$serverUrl/api/task-types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "taskType": {
      "id": 1,
      "code": "script",
      "name": "Shell Script",
      "category": "script",
      "description": null,
      "optionTypes": [
        {
          "id": 254,
          "name": "Script",
          "code": "script",
          "description": null,
          "fieldName": "script",
          "fieldLabel": "Script",
          "fieldContext": "taskOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "type": "code-editor",
          "advanced": false,
          "required": false,
          "editable": false,
          "config": {
          },
          "displayOrder": 5,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": null,
          "dependsOnCode": null,
          "contextualDefault": null
        }
      ]
    }
}

This endpoint will retrieve a specific task type by id

HTTP Request

GET $serverUrl/api/task-types/:id

URL Parameters

Parameter Description
ID The ID of the task type

Workflows

Provides API interfaces for managing the creation and modification of automation workflows. Workflows, also called Task Sets, are a collection of tasks that are organized in phases. A task phase determines if/when each task runs.

A Workflow may also be referred to as a Task Set or taskSet.

curl "$serverUrl/api/task-sets" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "taskSets": [
    {
      "id": 13,
      "name": "my workflow",
      "description": null,
      "dateCreated": "2017-06-26T15:36:19+0000",
      "lastUpdated": "2017-06-26T15:44:38+0000",
      "accountId": 1,
      "tasks": [
        8
      ],
      "taskSetTasks": [
        {
          "id": 51,
          "taskPhase": "provision",
          "taskOrder": 2,
          "task": {
            "id": 8,
            "name": "my task",
            "taskType": {
              "id": 1,
              "code": "script",
              "name": "Shell Script"
            },
            "taskOptions": {
              "script": "echo  \"hello\""
            }
          }
        }
      ]
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all workflows.

HTTP Request

GET $serverUrl/api/task-sets

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by matching name
name Filter by name

Get a Specific Workflow

curl "$serverUrl/api/task-sets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "taskSet": {
    "id": 8,
    "name": "uname",
    "description": "",
    "dateCreated": "2017-05-24T20:24:02+0000",
    "lastUpdated": "2017-05-24T20:24:02+0000",
    "accountId": 1,
    "tasks": [
      10
    ],
    "taskSetTasks": [
      {
        "id": 33,
        "taskPhase": "postProvision",
        "taskOrder": 0,
        "task": {
          "id": 10,
          "name": "uname",
          "taskType": {
            "id": 1,
            "code": "script",
            "name": "Shell Script"
          },
          "taskOptions": {
            "script": "echo `uname a`"
          }
        }
      }
    ]
  }
}

This endpoint will retrieve a specific workflow by id

HTTP Request

GET $serverUrl/api/task-sets/:id

URL Parameters

Parameter Description
ID The ID of the workflow

Create a Workflow

curl -XPOST "$serverUrl/api/task-sets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"taskSet": {
    "name": "my workflow",
    "tasks": [
      {
        "taskId": 3
      },
      {
        "taskId": 8
      },
      {
        "taskId": 9,
        "taskPhase": "postProvision"
      }
    ]
  }}'

The above command returns JSON structured like getting a single workflow:

HTTP Request

POST $serverUrl/api/task-sets

JSON Parameters

Parameter Default Description
name A unique name for the workflow
description A description of the workflow
type provision Workflow type. Pass operation for operational workflows.
optionTypes [] List of option type IDs for use with operational workflow configuration.
tasks [] List of task objects in order
tasks.taskId Task ID
tasks.taskPhase provision Task Phase. Pass operation for operational workflows.

Create an Operational Workflow

curl -XPOST "$serverUrl/api/task-sets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"taskSet": {
    "name": "test workflow",
    "type": "operation",
    "optionTypes": [3,4,5],
    "tasks": [
      {
        "taskId": 3,
        "phase": "operation"
      }
    ]
  }}'

The above command returns JSON structured like getting a single workflow:

HTTP Request

POST $serverUrl/api/task-sets

JSON Parameters

Parameter Default Description
name A unique name for the workflow
description A description of the workflow
type provision Workflow type. Pass operation for operational workflows.
optionTypes [] List of option type IDs for use with operational workflow configuration.
tasks [] List of task objects in order
tasks.taskId Task ID
tasks.taskPhase provision Task Phase. Pass operation for operational workflows

Updating a Workflow

curl -XPUT "$serverUrl/api/task-sets/5" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"taskSet":{
    "tasks": [
      {
        "taskId": 3
      }
    ]
  }}'

The above command returns JSON structured like getting a single workflow:

HTTP Request

PUT $serverUrl/api/task-sets/:id

URL Parameters

Parameter Description
ID The ID of the workflow

JSON Parameters

Parameter Default Description
name A unique name for the workflow
description A description of the workflow
tasks [] List of task objects in order
tasks.taskId Task ID
tasks.taskPhase provision Task Phase.

Delete a Workflow

curl -XDELETE "$serverUrl/api/task-sets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/task-sets/:id

URL Parameters

Parameter Description
ID The ID of the workflow

Execute a Workflow

curl -XPOST "$serverUrl/api/task-sets/5/execute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"job":{
    "targetType": "instance",
    "instances": [1],
    "customOptions": {
      "mysqlVersion":"5.7"
    }
  }}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint executes a workflow on the specified instances, servers or the appliance itself, depending on which targetType is specified. Workflows are executed asynchronously, so to see the process and event results you may fetch the job execution record. See Get a Specific Job Execution.

HTTP Request

POST $serverUrl/api/task-sets/:id/execute

URL Parameters

Parameter Description
ID The ID of the workflow

JSON Parameters

The following parameters are passed inside an object named job.

Parameter Default Description
name (workflow name) A name for the execution job. Can be used to find execution results with /api/processes?name=.
targetType The target context for task execution. Pass instance, server or appliance (None, execute locally on the appliance itself). This is required for tasks with executeTarget set to resource.
instances Array of Instance IDs. Only applicable for targetType is instance.
servers Array of Server IDs. Only applicable for targetType is server`.
customOptions Map of options to be used as values in the workflow tasks. These correspond to option types.
customConfig String of custom configuration values as JSON.

Power Schedules

Power Schedules can be configured to automatically power on and off your instances and servers.

curl "$serverUrl/api/power-schedules" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "schedules": [
    {
      "id": 1,
      "name": "weekday daytime",
      "description": "weekday daytime hours",
      "enabled": true,
      "scheduleType": "power",
      "scheduleTimezone": "America/New_York",
      "sundayOn": 0.0,
      "sundayOff": 0.0,
      "mondayOn": 7.0,
      "mondayOff": 19.0,
      "tuesdayOn": 7.0,
      "tuesdayOff": 19.0,
      "wednesdayOn": 7.0,
      "wednesdayOff": 19.0,
      "thursdayOn": 7.0,
      "thursdayOff": 19.0,
      "fridayOn": 7.0,
      "fridayOff": 19.0,
      "saturdayOn": 0.0,
      "saturdayOff": 0.0,
      "totalMonthlyHoursSaved": 463.32,
      "dateCreated": "2018-03-01T07:56:38+0000",
      "lastUpdated": "2018-09-13T21:38:19+0000"
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all power schedules associated with the account.

HTTP Request

GET $serverUrl/api/power-schedules

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Power Schedule

curl "$serverUrl/api/power-schedules/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "schedule": {
    "id": 2,
    "name": "my hours",
    "description": null,
    "enabled": true,
    "scheduleType": "power",
    "scheduleTimezone": "America/New_York",
    "sundayOn": 5.5,
    "sundayOff": 24.0,
    "mondayOn": 0.0,
    "mondayOff": 24.0,
    "tuesdayOn": 0.0,
    "tuesdayOff": 24.0,
    "wednesdayOn": 0.0,
    "wednesdayOff": 24.0,
    "thursdayOn": 0.0,
    "thursdayOff": 24.0,
    "fridayOn": 0.0,
    "fridayOff": 24.0,
    "saturdayOn": 0.0,
    "saturdayOff": 24.0,
    "totalMonthlyHoursSaved": 23.595,
    "dateCreated": "2018-03-07T18:34:08+0000",
    "lastUpdated": "2018-03-07T18:34:08+0000"
  },
  "instances": [

  ],
  "servers": [

  ]
}

This endpoint retrieves a specific power schedule.

HTTP Request

GET $serverUrl/api/power-schedules/:id

URL Parameters

Parameter Description
ID The ID of the power schedule to retrieve

Create a Power Schedule

curl -XPOST "$serverUrl/api/power-schedules" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "name": "business hours only",
    "description": null,
    "enabled": true,
    "scheduleType": "power",
    "scheduleTimezone": "UTC",
    "sundayOn": 0,
    "sundayOff": 0,
    "mondayOn": 7,
    "mondayOff": 19,
    "tuesdayOn": 7,
    "tuesdayOff": 19,
    "wednesdayOn": 7,
    "wednesdayOff": 19,
    "thursdayOn": 7,
    "thursdayOff": 19,
    "fridayOn": 7,
    "fridayOff": 19,
    "saturdayOn": 0,
    "saturdayOff": 0,
    "enabled": true
  }
}'

The above command returns JSON structured like getting a single power schedule:

HTTP Request

POST $serverUrl/api/power-schedules

JSON Parameters

Parameter Default Description
name A name for the power schedule
description A description for the power schedule
scheduleType Type of schedule: Power (power), Power Off (power off)
scheduleTimezone UTC Time Zone eg. America/New_York, Europe/Amsterdam, etc.
enabled true Enabled
sundayOn 0 Saturday Start
sundayOff 24 Saturday End
mondayOn 0 Monday Start
mondayOff 24 Monday Stop
tuesdayOn 0 Tuesday Start
tuesdayOff 24 Tuesday Stop
wednesdayOn 0 Wednesday Start
wednesdayOff 24 Wednesday Stop
thursdayOn 0 Thursday Start
thursdayOff 24 Thursday Stop
fridayOn 0 Friday Start
fridayOff 24 Friday Stop
saturdayOn 0 Saturday Start
saturdayOff 24 Saturday Stop

Update a Power Schedule

curl -XPUT "$serverUrl/api/power-schedules/2" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "mondayOff": 20,
    "tuesdayOff": 20,
    "wednesdayOff": 20,
    "thursdayOff": 20,
    "fridayOff": 15
  }
}'

The above command returns JSON structured like getting a single power schedule:

HTTP Request

PUT $serverUrl/api/power-schedules/:id

JSON Parameters

See Create.

Delete a Power Schedule

curl -XDELETE "$serverUrl/api/power-schedules/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a power schedule from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/power-schedules/:id

URL Parameters

Parameter Description
ID The ID of the power schedule

Add Instances to a Power Schedule

curl -XPUT "$serverUrl/api/power-schedules/2/add-instances" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instances": [
    231, 232
  ]
}'

The above command returns JSON structured like this:

{
  "success": true
}

Add one or many instances to a power schedule.

HTTP Request

PUT $serverUrl/api/power-schedules/:id/add-instances

URL Parameters

Parameter Description
ID The ID of the power schedule

JSON Parameters

Parameter Default Description
instances Array of Instance IDs to add

Remove Instances from a Power Schedule

curl -XPUT "$serverUrl/api/power-schedules/2/remove-instances" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instances": [
    232
  ]
}'

The above command returns JSON structured like this:

{
  "success": true
}

Remove one or many instances from a power schedule.

HTTP Request

PUT $serverUrl/api/power-schedules/:id/remove-instances

URL Parameters

Parameter Description
ID The ID of the power schedule

JSON Parameters

Parameter Default Description
instances Array of Instance IDs to remove

Add Servers to a Power Schedule

curl -XPUT "$serverUrl/api/power-schedules/2/add-servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "servers": [
    6,7,8
  ]
}'

The above command returns JSON structured like this:

{
  "success": true
}

Add one or many servers to a power schedule.

HTTP Request

PUT $serverUrl/api/power-schedules/:id/add-servers

URL Parameters

Parameter Description
ID The ID of the power schedule

JSON Parameters

Parameter Default Description
servers Array of Server IDs to add

Remove Servers from a Power Schedule

curl -XPUT "$serverUrl/api/power-schedules/2/remove-servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "servers": [
    7,8
  ]
}'

The above command returns JSON structured like this:

{
  "success": true
}

Remove one or many servers from a power schedule.

HTTP Request

PUT $serverUrl/api/power-schedules/:id/remove-servers

URL Parameters

Parameter Description
ID The ID of the power schedule

JSON Parameters

Parameter Default Description
servers Array of Server IDs to remove

Execute Schedules

Execute Schedules are definitions for recurring schedules. These schedules can be used in your backup jobs.

curl "$serverUrl/api/execute-schedules" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "schedules": [
    {
      "id": 1,
      "name": "daily",
      "description": "Daily at Midnight",
      "enabled": true,
      "scheduleType": "execute",
      "scheduleTimezone": "America/New_York",
      "cron": "0 0 * * *"
      "dateCreated": "2018-03-01T07:56:38+0000",
      "lastUpdated": "2018-09-13T21:38:19+0000"
    },
    {
      "id": 2,
      "name": "weekly",
      "description": "Weekly on Sunday at Midnight",
      "enabled": true,
      "scheduleType": "execute",
      "scheduleTimezone": "America/New_York",
      "cron": "0 0 * * 7"
      "dateCreated": "2018-03-01T07:56:38+0000",
      "lastUpdated": "2018-09-13T21:38:19+0000"
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all execute schedules associated with the account.

HTTP Request

GET $serverUrl/api/execute-schedules

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Execute Schedule

curl "$serverUrl/api/execute-schedules/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "schedule": {
    "id": 1,
    "name": "daily",
    "description": "Daily at Midnight",
    "enabled": true,
    "scheduleType": "execute",
    "scheduleTimezone": "America/New_York",
    "cron": "0 0 * * *"
    "dateCreated": "2018-03-01T07:56:38+0000",
    "lastUpdated": "2018-09-13T21:38:19+0000"
  }
}

This endpoint retrieves a specific execute schedule.

HTTP Request

GET $serverUrl/api/execute-schedules/:id

URL Parameters

Parameter Description
ID The ID of the execute schedule to retrieve

Create an Execute Schedule

curl -XPOST "$serverUrl/api/execute-schedules" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "name": "Friday at Midnight",
    "description": null,
    "enabled": true,
    "scheduleType": "execute",
    "scheduleTimezone": "UTC",
    "cron": "0 0 * * 5"
  }
}'

The above command returns JSON structured like getting a single execute schedule:

HTTP Request

POST $serverUrl/api/execute-schedules

JSON Parameters

Parameter Default Description
name A name for the execute schedule
description A description for the execute schedule
scheduleType Type of schedule: Execute (execute)
scheduleTimezone UTC Time Zone eg. America/New_York, Europe/Amsterdam, etc.
cron 0 0 * * * Cron Expression. The default is daily at midnight
enabled true Enabled

Update an Execute Schedule

curl -XPUT "$serverUrl/api/execute-schedules/2" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "description": "Daily at 2AM",
    "cron": "0 2 * * *"
  }
}'

The above command returns JSON structured like getting a single execute schedule:

HTTP Request

PUT $serverUrl/api/execute-schedules/:id

JSON Parameters

See Create.

Delete an Execute Schedule

curl -XDELETE "$serverUrl/api/execute-schedules/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete an execute schedule from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/execute-schedules/:id

URL Parameters

Parameter Description
ID The ID of the execute schedule

Execution Request

Provides API interfaces for executing an arbitrary script or command on an instance, container or host.

curl -XPOST "$serverUrl/api/execution-request/execute?instanceId=256" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "script": "uname -a"
}'

The above command returns JSON structured like this:

{
  "executionRequest": {
    "id": 24,
    "uniqueId": "f22e1292-4407-44c0-b2c7-698ee2241491",
    "containerId": null,
    "serverId": null,
    "instanceId": 256,
    "stdOut": null,
    "stdErr": null,
    "exitCode": null,
    "status": "pending",
    "expiresAt": "2018-11-30T18:23:01+0000",
    "createdById": 1
  }
}

HTTP Request

POST $serverUrl/api/execution-request/execute

Query Parameters

Parameter Default Description
instanceId Instance ID to execute request on
containerId Container ID to execute request on
serverId Host ID to execute request on

JSON Parameters

Parameter Default Description
script A script or command to be executed

This endpoint executes the provided script on the specified instance, container or server.

Get a Specific Execution Request

curl "$serverUrl/api/execution-request/f22e1292-4407-44c0-b2c7-698ee2241491" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "executionRequest": {
    "id": 24,
    "uniqueId": "f22e1292-4407-44c0-b2c7-698ee2241491",
    "containerId": null,
    "serverId": null,
    "instanceId": 256,
    "stdOut": "Linux apachetest 3.19.0-69-generic #77~14.04.1-Ubuntu SMP Tue Aug 30 01:29:21 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux\n",
    "stdErr": null,
    "exitCode": 0,
    "status": "complete",
    "expiresAt": "2018-11-30T18:23:02+0000",
    "createdById": 1
  }
}

HTTP Request

GET $serverUrl/api/execution-request/:uniqueId

URL Parameters

Parameter Description
uniqueId The Unique ID of the execution request

This endpoint retrieves a specific execution request.

Virtual Images

Virtual Images can be managed via the API.

Get List of Virtual Images

curl "$serverUrl/api/virtual-images"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "virtualImages": [
    {
      "id": 470,
      "name": "Morpheus MongoDB 3.2 on Ubuntu 14.04.3 v2",
      "description": null,
      "ownerId": null,
      "tenant": null,
      "imageType": "ovf",
      "userUploaded": false,
      "userDefined": false,
      "systemImage": true,
      "isCloudInit": true,
      "sshUsername": "ubuntu",
      "sshPassword": "************",
      "sshKey": null,
      "osType": {
        "id": 5,
        "code": "ubuntu.14.04.64",
        "name": "ubuntu 14 64-bit",
        "description": null,
        "vendor": "canonical",
        "category": "ubuntu",
        "osFamily": "debian",
        "osVersion": "14.04",
        "bitCount": 64,
        "platform": "linux"
      },
      "minRam": null,
      "minRamGB": null,
      "minDisk": 2147483648,
      "minDiskGB": 2,
      "rawSize": null,
      "rawSizeGB": null,
      "trialVersion": false,
      "virtioSupported": true,
      "isAutoJoinDomain": null,
      "vmToolsInstalled": true,
      "installAgent": true,
      "isForceCustomization": null,
      "isSysprep": null,
      "userData": null,
      "consoleKeymap": null,
      "storageProvider": null,
      "externalId": null,
      "visibility": "private",
      "accounts": [

      ],
      "config": {
      },
      "volumes": [
        {
          "name": "root",
          "maxStorage": 2147483648,
          "rawSize": 2147483648,
          "size": 2,
          "rootVolume": true,
          "resizeable": true
        }
      ],
      "storageControllers": [
        {
          "name": "SCSI 0",
          "type": {
            "id": 4,
            "code": "vmware-lsiLogic",
            "name": "SCSI LSI Logic Parallel"
          },
          "maxDevices": 15,
          "reservedUnitNumber": 7
        },
        {
          "name": "IDE 0",
          "type": {
            "id": 2,
            "code": "vmware-ide",
            "name": "IDE"
          },
          "maxDevices": 2,
          "reservedUnitNumber": -1
        },
        {
          "name": "IDE 1",
          "type": {
            "id": 2,
            "code": "vmware-ide",
            "name": "IDE"
          },
          "maxDevices": 2,
          "reservedUnitNumber": -1
        }
      ],
      "networkInterfaces": [
        {
          "name": "eth0",
          "description": null,
          "dhcp": true,
          "primaryInterface": true,
          "type": {
            "id": 2,
            "code": "e1000",
            "name": "E1000"
          },
          "ipMode": null
        }
      ],
      "tags": [

      ],
      "dateCreated": null,
      "lastUpdated": null,
      "status": "Active"
    }
  ],
  "filterType": "User",
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 25,
    "total": 43
  }
}

This endpoint retrieves a list of virtual images for the specified filter.

HTTP Request

GET $serverUrl/api/virtual-images

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
name Filter by name
phrase Filter by wildcard search of name
lastUpdated Date filter, restricts query to only records with a timestamp is more recent or equal to the date specified
filterType “User” Filter by type, “User”, “System”, “Synced”, or “All”
imageType Filter by image type code, “vmware”, “ami”, etc
tags Filter by tags (metadata). This allows filtering by arbitrary tag names and values like this tags.foo=bar.

Get a Specific Virtual Image

curl "$serverUrl/api/virtual-images/764" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "virtualImage": {
    "id": 470,
    "name": "Morpheus MongoDB 3.2 on Ubuntu 14.04.3 v2",
    "description": null,
    "ownerId": null,
    "tenant": null,
    "imageType": "ovf",
    "userUploaded": false,
    "userDefined": false,
    "systemImage": true,
    "isCloudInit": true,
    "sshUsername": "ubuntu",
    "sshPassword": "************",
    "sshKey": null,
    "osType": {
      "id": 5,
      "code": "ubuntu.14.04.64",
      "name": "ubuntu 14 64-bit",
      "description": null,
      "vendor": "canonical",
      "category": "ubuntu",
      "osFamily": "debian",
      "osVersion": "14.04",
      "bitCount": 64,
      "platform": "linux"
    },
    "minRam": null,
    "minRamGB": null,
    "minDisk": 2147483648,
    "minDiskGB": 2,
    "rawSize": null,
    "rawSizeGB": null,
    "trialVersion": false,
    "virtioSupported": true,
    "isAutoJoinDomain": null,
    "vmToolsInstalled": true,
    "installAgent": true,
    "isForceCustomization": null,
    "isSysprep": null,
    "userData": null,
    "consoleKeymap": null,
    "storageProvider": null,
    "externalId": null,
    "visibility": "private",
    "accounts": [

    ],
    "config": {
    },
    "volumes": [
      {
        "name": "root",
        "maxStorage": 2147483648,
        "rawSize": 2147483648,
        "size": 2,
        "rootVolume": true,
        "resizeable": true
      }
    ],
    "storageControllers": [
      {
        "name": "SCSI 0",
        "type": {
          "id": 4,
          "code": "vmware-lsiLogic",
          "name": "SCSI LSI Logic Parallel"
        },
        "maxDevices": 15,
        "reservedUnitNumber": 7
      },
      {
        "name": "IDE 0",
        "type": {
          "id": 2,
          "code": "vmware-ide",
          "name": "IDE"
        },
        "maxDevices": 2,
        "reservedUnitNumber": -1
      },
      {
        "name": "IDE 1",
        "type": {
          "id": 2,
          "code": "vmware-ide",
          "name": "IDE"
        },
        "maxDevices": 2,
        "reservedUnitNumber": -1
      }
    ],
    "networkInterfaces": [
      {
        "name": "eth0",
        "description": null,
        "dhcp": true,
        "primaryInterface": true,
        "type": {
          "id": 2,
          "code": "e1000",
          "name": "E1000"
        },
        "ipMode": null
      }
    ],
    "tags": [

    ],
    "dateCreated": null,
    "lastUpdated": null,
    "status": "Active"
  }
}

This endpoint retrieves a specific virtual image and its files.

HTTP Request

GET $serverUrl/api/virtual-images/:id

URL Parameters

Parameter Description
id The ID of the virtual image

Create a Virtual Image

curl -XPOST "$serverUrl/api/virtual-images" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"virtualImage":{
    "name": "testimage2",
    "imageType": "vmware",
    "isCloudInit": true,
    "installAgent": true,
    "sshUsername": "root",
    "sshPassword": "mygoodpassword123",
    "sshKey": null,
    "osType": {
      "id": 9
    },
    "virtioSupported": true,
    "vmToolsInstalled": true,
    "config": {
    }
  }}'

The above command returns JSON structured like getting a single virtual image.

This endpoint creates a new virtual image, without any files yet.

HTTP Request

POST $serverUrl/api/virtual-images

JSON Virtual Image Parameters

Parameter Default Description
name A name for the virtual image
imageType Code of image type. eg. vmware, ami, etc.
storageProvider A Map containing the id of the Storage Provider
isCloudInit false Cloud Init Enabled? true or false
userData Cloud-Init User Data, a bash script
installAgent false Install Agent? true or false
sshUsername SSH Username
sshPassword SSH Password
sshKey SSH Key
osType A Map containing the id of the OS Type. This can also be passed as a string (code or name) instead.
visibility “private” private or public
accounts Array of tenant account ids that are allowed access.
isAutoJoinDomain false Auto Join Domain?
virtioSupported true VirtIO Drivers Loaded?
vmToolsInstalled true VM Tools Installed?
isForceCustomization false Force Guest Customization?
trialVersion false Trial Version
isSysprep false Sysprep Enabled?
config Map of configuration properties, varies by image type. See below for more information
tags Metadata tags, Array of objects having a name and value

Create an Azure Reference Virtual Image

curl -XPOST "$serverUrl/api/virtual-images" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"virtualImage":{
    "name": "azure-nginx-test",
    "imageType": "azure-reference",
    "isCloudInit": true,
    "installAgent": true,
    "sshUsername": "root",
    "sshPassword": "mygoodpassword123",
    "sshKey": null,
    "osType": {
      "id": 9
    },
    "config": {
      "publisher": "miri-infotech-pvt-ltd",
      "offer": "Nginx",
      "sku": "nginx",
      "version": "1.1.1"
    },
    "tags": [
      {"name": "Category", "value": "Web"}
    ]
  }}'

The above command returns JSON structured like getting a single virtual image.

This endpoint creates a new Azure Reference virtual image.

HTTP Request

POST $serverUrl/api/virtual-images

Azure Reference Virtual Image Parameters

Same as Create.

Azure Reference Config Parameters

Creating a virtual image of type Azure Reference requires the following settings to be passed under config.

Parameter Default Description
publisher The name of the publisher in the Azure Marketplace
offer The name of the offer in the Azure Marketplace
sku The name of the version in the Azure Marketplace
version The name of the version in the Azure Marketplace

Upload Virtual Image File

curl -XPOST "$serverUrl/api/virtual-images/765/upload?filename=disk-0.vmdk" \
  -H "Authorization: BEARER $accessToken" \
  --data-binary '@/path/to/file'

The above command returns JSON structure like this:

{
  "success": true
}

This will upload the file and associate it to the Virtual Image.

HTTP Request

POST $serverUrl/api/virtual-images/:id/upload

URL Parameters

Parameter Description
id The ID of the virtual image

Query Parameters

Parameter Description
url Download the file from a remote url. This can be used instead of uploading a local file.
filename Specify a filename for new file.

Remove Virtual Image File

curl -XDELETE "$serverUrl/api/virtual-images/765/files?filename=testimage.ovf" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/virtual-images/:id/files?filename=

URL Parameters

Parameter Description
id The ID of the virtual image

Query Parameters

Parameter Default Description
filename The name of the file to be deleted

Update a Virtual Image

curl -XPUT "$serverUrl/api/virtual-images/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"virtualImage":{
    "installAgent": true,
    "sshUsername": "root",
    "sshPassword": "aGreatpassword12345!"
    "addTags": [
      {"name": "Category", "value": "Cache"}
    ],
    "removeTags": [
      {"name": "OldThing"}
    ]
  }}'

The above command returns JSON structured like getting a single virtual image.

This endpoint updates an existing virtual image.

HTTP Request

PUT $serverUrl/api/virtual-images/:id

URL Parameters

Parameter Description
id The ID of the virtual image

JSON Update Virtual Image Parameters

Parameter Default Description
name A name for the virtual image
imageType Code of image type. eg. vmware, ami, etc.
storageProvider A Map containing the id of the Storage Provider
isCloudInit false Cloud Init Enabled? true or false
userData Cloud-Init User Data, a bash script
installAgent false Install Agent? true or false
sshUsername SSH Username
sshPassword SSH Password
sshKey SSH Key
osType A Map containing the id of the OS Type. This can also be passed as a string (code or name) instead.
visibility “private” private or public
accounts Array of tenant account ids that are allowed access.
isAutoJoinDomain false Auto Join Domain?
virtioSupported true VirtIO Drivers Loaded?
vmToolsInstalled true VM Tools Installed?
isForceCustomization false Force Guest Customization?
trialVersion false Trial Version
isSysprep false Sysprep Enabled?
config Map of configuration properties, varies by image type. See below for more information
tags Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified.
addTags Add or update value of Metadata tags, Array of objects having a name and value
removeTags Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed.

Delete a Virtual Image

curl -XDELETE "$serverUrl/api/virtual-images/765" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a virtual image and any associated files, use removeFromCloud=true to also delete image locations from all clouds.

HTTP Request

DELETE $serverUrl/api/virtual-images/:id

URL Parameters

Parameter Description
id The ID of the virtual image

Query Parameters

Parameter Default Description
removeFromCloud false Remove from all clouds, all the image locations will be deleted from the cloud as well.

Get a List of Virtual Image Locations

curl "$serverUrl/api/virtual-images/17600/locations" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "locations": [
    {
      "id": 796792,
      "cloud": {
        "id": 39,
        "code": "dev-amazon",
        "name": "dev-amazon"
      },
      "code": "amazon.ec2.image.39.ami-04d00cc409aeccd32",
      "internalId": null,
      "externalId": "ami-04d00cc409aeccd32",
      "externalDiskId": "snap-0ad5833d9dcc3ce1f",
      "remotePath": null,
      "imagePath": null,
      "imageName": "CentOS-8.2-x86_64-Minimal-8GiB-HVM-20200616_131752-84a857fb-30b1-429f-8e92-3065cf289a61-ami-07f119b85966cd8a5.4",
      "imageRegion": "us-west-1",
      "imageFolder": null,
      "refType": "ComputeZone",
      "refId": 39,
      "nodeRefType": null,
      "nodeRefId": null,
      "subRefType": null,
      "subRefId": null,
      "isPublic": false,
      "systemImage": false,
      "diskIndex": 0,
      "pricePlan": null,
      "volumes": [

      ],
      "storageControllers": [

      ],
      "networkInterfaces": [

      ],
      "virtualImage": {
        "id": 17600,
        "code": "amazon.ec2.image.39.ami-04d00cc409aeccd32",
        "name": "CentOS-8.2-x86_64-Minimal-8GiB-HVM-20200616_131752-84a857fb-30b1-429f-8e92-3065cf289a61-ami-07f119b85966cd8a5.4",
        "imageType": "ami"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves a specific virtual image and its files.

HTTP Request

GET $serverUrl/api/virtual-images/:id

URL Parameters

Parameter Description
id The ID of the virtual image

Delete a Virtual Image Location

curl -XDELETE "$serverUrl/api/virtual-images/17600/locations/796792" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a virtual image location, use removeFromCloud=true to all also delete image locations from all clouds as well.

HTTP Request

DELETE $serverUrl/api/virtual-images/:id/locations/:locationId

URL Parameters

Parameter Description
id The ID of the virtual image
locationId ID of the virtual image location

Query Parameters

Parameter Default Description
removeFromCloud false Remove from cloud, the location will be deleted from the cloud as well.

Library

The Library API endpoints provide the management of Instance Types, Layouts, Node Types, and more.

Instance Types

Provides API interfaces for managing instance types within Morpheus.

This API is for management of the library. To query instance types during provisioning, use Get All Instance Types For Provisioning.

Get All Instance Types

curl "$serverUrl/api/library/instance-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instanceTypes": [
    {
      "id": 6,
      "account": null,
      "name": "Apache",
      "code": "apache",
      "description": "An open-source modern web server common on many websites today. A secure, efficient and extensible server that provides HTTP services in sync with the current HTTP standards.",
      "provisionTypeCode": "mixed",
      "category": "web",
      "active": true,
      "environmentPrefix": "APACHE",
      "visibility": "public",
      "featured": false,
      "versions": [
        "2.4"
      ],
      "instanceTypeLayouts": [
        {
          "id": 574,
          "name": "Amazon Apache on CentOS 7.3",
          "provisionTypeCode": "amazon"
        },
        {
          "id": 30,
          "name": "Fusion Apache on Ubuntu 14.04",
          "provisionTypeCode": "fusion"
        }
      ]
    }
  ],
  "meta": {
    "size": 25,
    "total": 122,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all instance types.

HTTP Request

GET $serverUrl/api/library/instance-types

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name or code, restricts query to only load instance types which contain the phrase specified
name Name filter, restricts query to only load type matching name specified
code Code filter, restricts query to only load type matching code specified
featured Filter by featured, eg. true or false

Get a Specific Instance Type

curl "$serverUrl/api/library/instance-types/6" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instanceType": {
    "id": 6,
    "account": null,
    "name": "Apache",
    "code": "apache",
    "description": "An open-source modern web server common on many websites today. A secure, efficient and extensible server that provides HTTP services in sync with the current HTTP standards.",
    "provisionTypeCode": "mixed",
    "category": "web",
    "active": true,
    "hasProvisioningStep": false,
    "hasDeployment": true,
    "hasConfig": true,
    "hasSettings": false,
    "hasAutoScale": true,
    "proxyType": "httpServer",
    "proxyPort": 80,
    "proxyProtocol": "HTTP",
    "environmentPrefix": "APACHE",
    "backupType": "lvmSnapshot",
    "config": {
    },
    "visibility": "public",
    "featured": false,
    "versions": [
      "2.4"
    ],
    "instanceTypeLayouts": [
      {
        "id": 974,
        "instanceType": {
          "id": 6,
          "name": "Apache",
          "code": "apache"
        },
        "account": null,
        "code": "apache-opentelekom-2.4-centos-7.3",
        "name": "Open Telekom Apache on CentOS 7.3",
        "instanceVersion": "2.4",
        "description": "This will provision a single process with no redundancy",
        "creatable": true,
        "memoryRequirement": 1073741824,
        "sortOrder": 100,
        "supportsConvertToManaged": null,
        "provisionType": {
          "id": 44,
          "code": "opentelekom",
          "name": "Open Telekom"
        },
        "taskSets": [

        ],
        "containerTypes": [
          {
            "id": 927,
            "account": null,
            "name": "Apache 2.4",
            "shortName": "apache",
            "code": "apache-opentelekom-2.4-centos-7.3",
            "containerVersion": "2.4",
            "provisionType": {
              "id": 44,
              "name": "Open Telekom",
              "code": "opentelekom"
            },
            "virtualImage": {
              "id": 556,
              "name": "Morpheus Apache 2.4 on CentOS 7.3"
            },
            "category": "apache",
            "config": {
            },
            "containerPorts": [
              {
                "id": 8,
                "name": "Http",
                "port": 80,
                "loadBalanceProtocol": "http",
                "exportName": "HTTP"
              },
              {
                "id": 9,
                "name": "Https",
                "port": 443,
                "loadBalanceProtocol": "https",
                "exportName": "HTTPS"
              }
            ],
            "containerScripts": [
              {
                "id": 4,
                "name": "apache vm entrypoint"
              },
              {
                "id": 88,
                "name": "apache stop"
              },
              {
                "id": 89,
                "name": "apache start"
              }
            ],
            "containerTemplates": [

            ],
            "environmentVariables": [

            ]
          }
        ],
        "mounts": [

        ],
        "ports": [
          {
            "id": 8,
            "code": "apache.80",
            "name": "Http",
            "shortName": "http",
            "internalPort": 80,
            "externalPort": 80,
            "loadBalancePort": null,
            "sortOrder": 0,
            "loadBalanceProtocol": "http",
            "loadBalance": true,
            "visible": true
          },
          {
            "id": 9,
            "code": "apache.443",
            "name": "Https",
            "shortName": "https",
            "internalPort": 443,
            "externalPort": 443,
            "loadBalancePort": null,
            "sortOrder": 1,
            "loadBalanceProtocol": "https",
            "loadBalance": true,
            "visible": true
          }
        ],
        "optionTypes": [

        ],
        "environmentVariables": [

        ],
        "specTemplates": [

        ]
      },
      {
        "id": 1179,
        "instanceType": {
          "id": 6,
          "name": "Apache",
          "code": "apache"
        },
        "account": null,
        "code": "apache-bluemix-2.4-ubuntu-16.04-single",
        "name": "IBM Cloud Apache",
        "instanceVersion": "2.4",
        "description": "This will provision a single process with no redundancy",
        "creatable": true,
        "memoryRequirement": null,
        "sortOrder": 10,
        "supportsConvertToManaged": false,
        "provisionType": {
          "id": 35,
          "code": "bluemix",
          "name": "IBM Cloud"
        },
        "taskSets": [

        ],
        "containerTypes": [
          {
            "id": 1134,
            "account": null,
            "name": "Apache 2.4",
            "shortName": "apache",
            "code": "apache-bluemix-2.4-ubuntu-16.04",
            "containerVersion": "2.4",
            "provisionType": {
              "id": 35,
              "name": "IBM Cloud",
              "code": "bluemix"
            },
            "virtualImage": {
              "id": 2037,
              "name": "Morpheus ubuntu 16.04"
            },
            "category": "apache",
            "config": {
            },
            "containerPorts": [
              {
                "id": 8,
                "name": "Http",
                "port": 80,
                "loadBalanceProtocol": "http",
                "exportName": "HTTP"
              },
              {
                "id": 9,
                "name": "Https",
                "port": 443,
                "loadBalanceProtocol": "https",
                "exportName": "HTTPS"
              }
            ],
            "containerScripts": [
              {
                "id": 4,
                "name": "apache vm entrypoint"
              },
              {
                "id": 5,
                "name": "apache stop"
              },
              {
                "id": 6,
                "name": "apache start"
              }
            ],
            "containerTemplates": [

            ],
            "environmentVariables": [

            ]
          }
        ],
        "mounts": [

        ],
        "ports": [
          {
            "id": 8,
            "code": "apache.80",
            "name": "Http",
            "shortName": "http",
            "internalPort": 80,
            "externalPort": 80,
            "loadBalancePort": null,
            "sortOrder": 0,
            "loadBalanceProtocol": "http",
            "loadBalance": true,
            "visible": true
          },
          {
            "id": 9,
            "code": "apache.443",
            "name": "Https",
            "shortName": "https",
            "internalPort": 443,
            "externalPort": 443,
            "loadBalancePort": null,
            "sortOrder": 1,
            "loadBalanceProtocol": "https",
            "loadBalance": true,
            "visible": true
          }
        ],
        "optionTypes": [

        ],
        "environmentVariables": [

        ],
        "specTemplates": [

        ]
      },
      {
        "id": 292,
        "instanceType": {
          "id": 6,
          "name": "Apache",
          "code": "apache"
        },
        "account": null,
        "code": "apache-virtualbox-2.4",
        "name": "VirtualBox Apache 2.4 on Ubuntu 14.04",
        "instanceVersion": "2.4",
        "description": "This will provision a single process with no redundancy",
        "creatable": true,
        "memoryRequirement": null,
        "sortOrder": 10,
        "supportsConvertToManaged": null,
        "provisionType": {
          "id": 22,
          "code": "virtualbox",
          "name": "VirtualBox"
        },
        "taskSets": [

        ],
        "containerTypes": [
          {
            "id": 299,
            "account": null,
            "name": "Apache 2.4",
            "shortName": "apache",
            "code": "apache-virtualbox-2.4",
            "containerVersion": "2.4",
            "provisionType": {
              "id": 22,
              "name": "VirtualBox",
              "code": "virtualbox"
            },
            "virtualImage": {
              "id": 175,
              "name": "ubuntu-14_04-apache-2_4-1"
            },
            "category": "apache",
            "config": {
            },
            "containerPorts": [
              {
                "id": 8,
                "name": "Http",
                "port": 80,
                "loadBalanceProtocol": "http",
                "exportName": "HTTP"
              },
              {
                "id": 9,
                "name": "Https",
                "port": 443,
                "loadBalanceProtocol": "https",
                "exportName": "HTTPS"
              }
            ],
            "containerScripts": [
              {
                "id": 4,
                "name": "apache vm entrypoint"
              },
              {
                "id": 5,
                "name": "apache stop"
              },
              {
                "id": 6,
                "name": "apache start"
              }
            ],
            "containerTemplates": [

            ],
            "environmentVariables": [

            ]
          }
        ],
        "mounts": [

        ],
        "ports": [
          {
            "id": 8,
            "code": "apache.80",
            "name": "Http",
            "shortName": "http",
            "internalPort": 80,
            "externalPort": 80,
            "loadBalancePort": null,
            "sortOrder": 0,
            "loadBalanceProtocol": "http",
            "loadBalance": true,
            "visible": true
          },
          {
            "id": 9,
            "code": "apache.443",
            "name": "Https",
            "shortName": "https",
            "internalPort": 443,
            "externalPort": 443,
            "loadBalancePort": null,
            "sortOrder": 1,
            "loadBalanceProtocol": "https",
            "loadBalance": true,
            "visible": true
          }
        ],
        "optionTypes": [

        ],
        "environmentVariables": [

        ],
        "specTemplates": [

        ]
      }
    ],
    "optionTypes": [

    ],
    "environmentVariables": [

    ]
  }
}

This endpoint retrieves a specific instance type.

HTTP Request

GET $serverUrl/api/library/instance-types/:id

URL Parameters

Parameter Description
id ID of the instance type

Create an Instance Type

Use this command to create an instance type.

curl -XPOST "$serverUrl/api/library/instance-types" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceType": {
    "name": "Foobar",
    "code": "foobar",
    "description": "An example instance type",
    "category": "web",
    "visibility": "private",
    "environmentPrefix": "FOOBAR_",
    "hasSettings": true,
    "hasAutoScale": true,
    "hasDeployment": true,
    "optionTypes": [
      100
    ],
    "environmentVariables": [
      {
        "name": "foo",
        "value": "bar",
        "masked": false,
        "export": false
      }
    ],
  }
}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/library/instance-types

JSON Parameters

Parameter Required Description
name Y Instance type name
description N Instance type description
code N Instance type code
category N Category
visibility N Visibility. Default is private.
featured N Featured, set to true or false.
hasSettings N Enable Settings, set to true or false.
hasAutoScale N Enable Scaling (Horizontal), set to true or false.
hasDeployment N Supports Deployments, set to true or false.
environmentPrefix N Environment Prefix, can be used to make exported evars unique.
environmentVariables N Array of instance type env variables, see Environment Variables
optionTypes N Array of instance type option type IDs, see Option Types

Environment Variable Parameters

The environmentVariables parameter is array of env objects with following fields:

Parameter Required Description
name Y Environment variable name
value N Sets fixed value for variable
masked N Can be used to enable / disable masking of variable, default is off
export N Can be used to enable / disable export of variable, default is off

Update an Instance Type

Use this command to update an existing instance type.

curl -XPUT "$serverUrl/api/library/instance-types/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"instanceType": {
        "description": "This is a test."
      }}

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/instance-types/:id

URL Parameters

Parameter Description
id The ID of the instance type

JSON Parameters

Same as Create.

curl -XPUT "$serverUrl/api/library/instance-types/:id/toggle-featured" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON structured like this:

{
  "success": true
}

Use this command to toggle the featured flag for an existing instance type. This will change the value from false to true, or from true to false.

HTTP Request

PUT $serverUrl/api/library/instance-types/:id/toggle-featured

URL Parameters

Parameter Description
id The ID of the instance type

Update Logo For Instance Type

curl -XPOST "$serverUrl/api/library/instance-types/:id/update-logo" \
  -H "Authorization: BEARER $accessToken"
  -F 'logo=@filename'

The above command returns JSON structured like this:

{
  "success": true
}

Use this command to update the logo image for an existing instance type. This endpoint expects multipart form data as the request format, not JSON.

HTTP Request

POST $serverUrl/api/library/instance-types/:id/update-logo

URL Parameters

Parameter Description
id The ID of the instance type

Parameters

Parameter Default Description
logo Logo File png,jpg,svg

Delete an Instance Type

curl -XDELETE "$serverUrl/api/library/instance-types/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete an instance type

HTTP Request

DELETE $serverUrl/api/library/instance-types/:id

URL Parameters

Parameter Description
id The ID of the instance type

Layouts

Provides API interfaces for managing layouts within Morpheus.

A Layout may also be referred to as an Instance Type Layout or instanceTypeLayout.

Get All Layouts

curl "$serverUrl/api/library/layouts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instanceTypeLayouts": [
    {
      "id": 574,
      "instanceType": {
        "id": 6,
        "name": "Apache",
        "code": "apache"
      },
      "account": null,
      "code": "apache-amazon-2.4-centos-7.3-single",
      "name": "Amazon Apache on CentOS 7.3",
      "instanceVersion": "2.4",
      "description": "This will provision a single process with no redundancy",
      "creatable": true,
      "memoryRequirement": null,
      "sortOrder": 100,
      "supportsConvertToManaged": null,
      "provisionType": {
        "id": 10,
        "code": "amazon",
        "name": "Amazon"
      },
      "taskSets": [

      ],
      "containerTypes": [
        {
          "id": 582,
          "account": null,
          "name": "Apache 2.4",
          "shortName": "apache",
          "code": "apache-amazon-2.4-centos-7.3",
          "containerVersion": "2.4",
          "provisionType": {
            "id": 10,
            "name": "Amazon",
            "code": "amazon"
          },
          "virtualImage": {
            "id": 2020,
            "name": "Morpheus Apache 2.4 on CentOS 7.3"
          },
          "category": "apache",
          "config": {
          },
          "containerPorts": [
            {
              "id": 8,
              "name": "Http",
              "port": 80,
              "loadBalanceProtocol": "http",
              "exportName": "HTTP"
            },
            {
              "id": 9,
              "name": "Https",
              "port": 443,
              "loadBalanceProtocol": "https",
              "exportName": "HTTPS"
            }
          ],
          "containerScripts": [
            {
              "id": 90,
              "name": "apache folder config"
            },
            {
              "id": 4,
              "name": "apache vm entrypoint"
            },
            {
              "id": 88,
              "name": "apache stop"
            },
            {
              "id": 89,
              "name": "apache start"
            }
          ],
          "containerTemplates": [

          ],
          "environmentVariables": [

          ]
        }
      ],
      "mounts": [

      ],
      "ports": [
        {
          "id": 8,
          "code": "apache.80",
          "name": "Http",
          "shortName": "http",
          "internalPort": 80,
          "externalPort": 80,
          "loadBalancePort": null,
          "sortOrder": 0,
          "loadBalanceProtocol": "http",
          "loadBalance": true,
          "visible": true
        },
        {
          "id": 9,
          "code": "apache.443",
          "name": "Https",
          "shortName": "https",
          "internalPort": 443,
          "externalPort": 443,
          "loadBalancePort": null,
          "sortOrder": 1,
          "loadBalanceProtocol": "https",
          "loadBalance": true,
          "visible": true
        }
      ],
      "optionTypes": [

      ],
      "environmentVariables": [

      ],
      "specTemplates": [

      ]
    }
  ],
  "meta": {
    "size": 25,
    "total": 1241,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all layouts.

HTTP Request

GET $serverUrl/api/library/layouts

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, description and provision type name, restricts query to only load layouts which contain the phrase specified
name Name filter, restricts query to only load layout matching name specified
code Code filter, restricts query to only load layout matching code specified
provisionType Provision type code filter, restricts query to only load layouts of specified provision type

Get All Layouts For an Instance Type

curl "$serverUrl/api/library/instance-types/1/layouts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instanceTypeLayouts": [
    {
      "id": 9,
      "instanceType": {
        "id": 1,
        "name": "ActiveMQ",
        "code": "activemq"
      },
      "account": null,
      "code": "activemq-amazon-5.11-single",
      "name": "Amazon ActiveMQ",
      "instanceVersion": "5.11",
      "description": "This will provision a single process with no redundancy",
      "creatable": true,
      "memoryRequirement": null,
      "sortOrder": 10,
      "supportsConvertToManaged": null,
      "provisionType": {
        "id": 10,
        "code": "amazon",
        "name": "Amazon"
      },
      "taskSets": [

      ],
      "containerTypes": [
        {
          "id": 9,
          "account": null,
          "name": "ActiveMQ 5.11",
          "shortName": "activemq",
          "code": "activemq-amazon-5.11",
          "containerVersion": "5.11",
          "provisionType": {
            "id": 10,
            "name": "Amazon",
            "code": "amazon"
          },
          "virtualImage": {
            "id": 7,
            "name": "ubuntu-14_04-activemq-5_11-morph.0.1"
          },
          "category": "activemq",
          "config": {
          },
          "containerPorts": [
            {
              "id": 1,
              "name": "Console",
              "port": 8161,
              "loadBalanceProtocol": null,
              "exportName": "CONSOLE"
            },
            {
              "id": 2,
              "name": "JMS Port",
              "port": 61616,
              "loadBalanceProtocol": null,
              "exportName": "JMS"
            },
            {
              "id": 3,
              "name": "AMQP Port",
              "port": 5672,
              "loadBalanceProtocol": null,
              "exportName": "AMQP"
            },
            {
              "id": 4,
              "name": "STOMP Port",
              "port": 61613,
              "loadBalanceProtocol": null,
              "exportName": "STOMP"
            },
            {
              "id": 5,
              "name": "MQTT Port",
              "port": 1883,
              "loadBalanceProtocol": null,
              "exportName": "MQTT"
            },
            {
              "id": 6,
              "name": "Websocket Port",
              "port": 61614,
              "loadBalanceProtocol": null,
              "exportName": "WEBSOCKET"
            }
          ],
          "containerScripts": [
            {
              "id": 1,
              "name": "activemq vm entrypoint"
            },
            {
              "id": 2,
              "name": "activemq stop"
            },
            {
              "id": 3,
              "name": "activemq start"
            }
          ],
          "containerTemplates": [
            {
              "id": 1,
              "name": "morpheus activemq config"
            }
          ],
          "environmentVariables": [

          ]
        }
      ],
      "mounts": [

      ],
      "ports": [
        {
          "id": 1,
          "code": "activemq.8161",
          "name": "Console",
          "shortName": "http",
          "internalPort": 8161,
          "externalPort": 8161,
          "loadBalancePort": null,
          "sortOrder": 0,
          "loadBalanceProtocol": null,
          "loadBalance": false,
          "visible": true
        },
        {
          "id": 2,
          "code": "activemq.61616",
          "name": "JMS Port",
          "shortName": "jms",
          "internalPort": 61616,
          "externalPort": 61616,
          "loadBalancePort": null,
          "sortOrder": 1,
          "loadBalanceProtocol": null,
          "loadBalance": false,
          "visible": true
        },
        {
          "id": 3,
          "code": "activemq.5672",
          "name": "AMQP Port",
          "shortName": "amqp",
          "internalPort": 5672,
          "externalPort": 5672,
          "loadBalancePort": null,
          "sortOrder": 2,
          "loadBalanceProtocol": null,
          "loadBalance": false,
          "visible": false
        },
        {
          "id": 4,
          "code": "activemq.61613",
          "name": "STOMP Port",
          "shortName": "stomp",
          "internalPort": 61613,
          "externalPort": 61613,
          "loadBalancePort": null,
          "sortOrder": 3,
          "loadBalanceProtocol": null,
          "loadBalance": false,
          "visible": false
        },
        {
          "id": 5,
          "code": "activemq.1883",
          "name": "MQTT Port",
          "shortName": "mqtt",
          "internalPort": 1883,
          "externalPort": 1883,
          "loadBalancePort": null,
          "sortOrder": 4,
          "loadBalanceProtocol": null,
          "loadBalance": false,
          "visible": false
        },
        {
          "id": 6,
          "code": "activemq.61614",
          "name": "Websocket Port",
          "shortName": "websocket",
          "internalPort": 61614,
          "externalPort": 61614,
          "loadBalancePort": null,
          "sortOrder": 5,
          "loadBalanceProtocol": null,
          "loadBalance": false,
          "visible": false
        }
      ],
      "optionTypes": [

      ],
      "environmentVariables": [

      ],
      "specTemplates": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 43,
    "max": 1,
    "offset": 0
  }
}

This endpoint retrieves all layouts for a specific instance type.

HTTP Request

GET $serverUrl/api/library/instance-types/:instanceTypeId/layouts

URL Parameters

Parameter Description
instanceTypeId ID of the instance type

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Name, description and provision type name, restricts query to only load layouts which contain the phrase specified
name Name filter, restricts query to only load layout matching name specified
code Code filter, restricts query to only load layout matching code specified
provisionType Provision type code filter, restricts query to only load layouts of specified provision type

Get a Specific Layout

curl "$serverUrl/api/library/layouts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "instanceTypeLayout": {
    "id": 1,
    "instanceType": {
      "id": 1,
      "name": "ActiveMQ",
      "code": "activemq"
    },
    "account": null,
    "code": "activemq-5.11",
    "name": "Docker ActiveMQ",
    "instanceVersion": "5.11",
    "description": "This will provision a single process with no redundancy",
    "creatable": true,
    "memoryRequirement": null,
    "sortOrder": 0,
    "supportsConvertToManaged": null,
    "provisionType": {
      "id": 1,
      "code": "docker",
      "name": "Docker"
    },
    "taskSets": [

    ],
    "containerTypes": [
      {
        "id": 1,
        "account": null,
        "name": "ActiveMQ 5.11",
        "shortName": "activemq",
        "code": "activemq-5.11",
        "containerVersion": "5.11-morph.0.1",
        "provisionType": {
          "id": 1,
          "name": "Docker",
          "code": "docker"
        },
        "virtualImage": null,
        "category": null,
        "config": {
        },
        "containerPorts": [
          {
            "id": 1,
            "name": "Console",
            "port": 8161,
            "loadBalanceProtocol": null,
            "exportName": "CONSOLE"
          },
          {
            "id": 2,
            "name": "JMS Port",
            "port": 61616,
            "loadBalanceProtocol": null,
            "exportName": "JMS"
          },
          {
            "id": 3,
            "name": "AMQP Port",
            "port": 5672,
            "loadBalanceProtocol": null,
            "exportName": "AMQP"
          },
          {
            "id": 4,
            "name": "STOMP Port",
            "port": 61613,
            "loadBalanceProtocol": null,
            "exportName": "STOMP"
          },
          {
            "id": 5,
            "name": "MQTT Port",
            "port": 1883,
            "loadBalanceProtocol": null,
            "exportName": "MQTT"
          },
          {
            "id": 6,
            "name": "Websocket Port",
            "port": 61614,
            "loadBalanceProtocol": null,
            "exportName": "WEBSOCKET"
          }
        ],
        "containerScripts": [

        ],
        "containerTemplates": [
          {
            "id": 1,
            "name": "morpheus activemq config"
          }
        ],
        "environmentVariables": [

        ]
      }
    ],
    "mounts": [
      {
        "id": 2,
        "code": "mount.data",
        "name": "data",
        "shortName": "data",
        "mountType": "volume",
        "sortOrder": 1,
        "required": false,
        "visible": true,
        "deployable": true,
        "canPersist": true
      }
    ],
    "ports": [
      {
        "id": 1,
        "code": "activemq.8161",
        "name": "Console",
        "shortName": "http",
        "internalPort": 8161,
        "externalPort": 8161,
        "loadBalancePort": null,
        "sortOrder": 0,
        "loadBalanceProtocol": null,
        "loadBalance": false,
        "visible": true
      },
      {
        "id": 2,
        "code": "activemq.61616",
        "name": "JMS Port",
        "shortName": "jms",
        "internalPort": 61616,
        "externalPort": 61616,
        "loadBalancePort": null,
        "sortOrder": 1,
        "loadBalanceProtocol": null,
        "loadBalance": false,
        "visible": true
      },
      {
        "id": 3,
        "code": "activemq.5672",
        "name": "AMQP Port",
        "shortName": "amqp",
        "internalPort": 5672,
        "externalPort": 5672,
        "loadBalancePort": null,
        "sortOrder": 2,
        "loadBalanceProtocol": null,
        "loadBalance": false,
        "visible": false
      },
      {
        "id": 4,
        "code": "activemq.61613",
        "name": "STOMP Port",
        "shortName": "stomp",
        "internalPort": 61613,
        "externalPort": 61613,
        "loadBalancePort": null,
        "sortOrder": 3,
        "loadBalanceProtocol": null,
        "loadBalance": false,
        "visible": false
      },
      {
        "id": 5,
        "code": "activemq.1883",
        "name": "MQTT Port",
        "shortName": "mqtt",
        "internalPort": 1883,
        "externalPort": 1883,
        "loadBalancePort": null,
        "sortOrder": 4,
        "loadBalanceProtocol": null,
        "loadBalance": false,
        "visible": false
      },
      {
        "id": 6,
        "code": "activemq.61614",
        "name": "Websocket Port",
        "shortName": "websocket",
        "internalPort": 61614,
        "externalPort": 61614,
        "loadBalancePort": null,
        "sortOrder": 5,
        "loadBalanceProtocol": null,
        "loadBalance": false,
        "visible": false
      }
    ],
    "optionTypes": [

    ],
    "environmentVariables": [

    ],
    "specTemplates": [

    ]
  }
}

This endpoint retrieves a specific layout.

HTTP Request

GET $serverUrl/api/library/layouts/:id

URL Parameters

Parameter Description
id ID of the layout

Create a Layout

curl -XPOST "$serverUrl/api/library/instance-types/:instanceTypeId/layouts" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceTypeLayout": {
    "name": "Foobar",
    "instanceVersion": "1.1",
    "description": "An example layout",
    "creatable": true,
    "provisionTypeCode": "amazon",
    "memoryRequirement": "10000",
    "hasAutoScale": true,
    "supportsConvertToManaged": true,
    "containerTypes": [
      1548
    ],
    "optionTypes": [

    ],
    "specTemplates": [

    ],
    "permissions": {
      "resourcePermissions": {
        "all":true
      }
    ]
  }
}'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

Use this command to create a layout.

HTTP Request

POST $serverUrl/api/library/instance-types/:instanceTypeId/layouts

URL Parameters

Parameter Description
instanceTypeId ID of the instance type

JSON Parameters

Parameter Required Description
name Y Layout name
description N Layout description
instanceVersion Y Version of the layout
creatable N Can be used to enable / disable the creatability of the layout. Default is on
hasAutoScale N Can be used to enable / disable the horizontal scaling. Default is off
supportsConvertToManaged N Can be used to enable / disable the supports convert to managed. Default is off
memoryRequirement N Memory requirement in megabytes
provisionTypeCode Y Provision type code
containerTypes N Array of layout node type IDs, see Node Types
optionTypes N Array of layout option type IDs, see Option Types
specTemplates N Array of layout spec template IDs, see Spec Templates
taskSetId N ID of Workflow
environmentVariables N Array of layout env variables, see Environment Variables
permissions N Permissions object for upgrading group access, see Permissions

Environment Variable Parameters

The environmentVariables parameter is array of env objects with following fields:

Parameter Required Description
name Y Environment variable name
value N Sets fixed value for variable
masked N Can be used to enable / disable masking of variable, default is off
export N Can be used to enable / disable export of variable, default is off

Permissions Parameters

The permissions parameter is an object with following fields:

Parameter Required Description
resourcePermissions N Object containing group access settings, see Group Access Parameters
Group Access Parameters

The resourcePermissions parameter is an object with following fields:

Parameter Required Description
all N Set to true to grant access to all groups
sites N Array of objects identifying groups with access eg. [{"id":1},{"id":2}]

Update a Layout

curl -XPUT "$serverUrl/api/library/layouts/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceTypeLayout": {
    "instanceVersion": "1.2",
    "containerTypes": [
      1550
    ]
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

Use this command to update an existing layout.

HTTP Request

PUT $serverUrl/api/library/layouts/:id

URL Parameters

Parameter Description
id The ID of the layout

JSON Parameters

Same as Create.

Update Layout Permissions

curl -XPOST "$serverUrl/api/library/layouts/:id/permissions" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceTypeLayout": {
    "permissions": {
      "resourcePermissions": {
        "all":false,
        "sites": [
          {"id": 2},
          {"id": 3}
        ]
      }
    ]
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

Use this command to update permissions for an existing layout.

HTTP Request

POST $serverUrl/api/library/layouts/:id/permissions

URL Parameters

Parameter Description
id The ID of the layout

JSON Parameters

Parameter Required Description
permissions N Permissions object for upgrading group access, see Permissions

Permissions Parameters

The permissions parameter is an object with following fields:

Parameter Required Description
resourcePermissions N Object containing permission settings, see Group Access Parameters
Group Access Parameters

The resourcePermissions parameter is an object with following fields:

Parameter Required Description
all N Set to true to grant access to all groups
sites N Array of objects identifying groups with access eg. [{"id":1},{"id":2}]

Delete a Layout

curl -XDELETE "$serverUrl/api/library/layouts/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a layout

HTTP Request

DELETE $serverUrl/api/library/layouts/:id

URL Parameters

Parameter Description
id The ID of the layout

Node Types

Provides API interfaces for managing node types within Morpheus.

A Node Type may also be referred to as a Container Type or containerType.

Get All Node Types

curl "$serverUrl/api/library/container-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containerTypes": [
    {
      "id": 1283,
      "account": null,
      "name": "Apache 2.4",
      "shortName": "apache",
      "code": "apache-upcloud-2.4-ubuntu-16.04",
      "containerVersion": "2.4",
      "provisionType": {
        "id": 30,
        "name": "UpCloud",
        "code": "upcloud"
      },
      "virtualImage": {
        "id": 6640,
        "name": "Morpheus ubuntu 16.04"
      },
      "category": "apache",
      "config": {
      },
      "containerPorts": [
        {
          "id": 8,
          "name": "Http",
          "port": 80,
          "loadBalanceProtocol": "http",
          "exportName": "HTTP"
        },
        {
          "id": 9,
          "name": "Https",
          "port": 443,
          "loadBalanceProtocol": "https",
          "exportName": "HTTPS"
        }
      ],
      "containerScripts": [
        {
          "id": 4,
          "name": "apache vm entrypoint"
        },
        {
          "id": 5,
          "name": "apache stop"
        },
        {
          "id": 6,
          "name": "apache start"
        }
      ],
      "containerTemplates": [

      ],
      "environmentVariables": [

      ]
    }
  ],
  "meta": {
    "size": 25,
    "total": 1285,
    "max": 25,
    "offset": 0
  }

This endpoint retrieves all node types.

HTTP Request

GET $serverUrl/api/library/container-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, description and provision type name, restricts query to only load node types which contain the phrase specified
name Name filter, restricts query to only load type matching name specified
code Code filter, restricts query to only load type matching code specified
provisionType Provision type code filter, restricts query to only load node types of specified provision type

Get a Specific Node Type

curl "$serverUrl/api/library/container-types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containerType": {
    "id": 1,
    "account": null,
    "name": "ActiveMQ 5.11",
    "shortName": "activemq",
    "code": "activemq-5.11",
    "containerVersion": "5.11-morph.0.1",
    "provisionType": {
      "id": 1,
      "name": "Docker",
      "code": "docker"
    },
    "virtualImage": null,
    "category": null,
    "config": {
    },
    "containerPorts": [
      {
        "id": 1,
        "name": "Console",
        "port": 8161,
        "loadBalanceProtocol": null,
        "exportName": "CONSOLE"
      },
      {
        "id": 2,
        "name": "JMS Port",
        "port": 61616,
        "loadBalanceProtocol": null,
        "exportName": "JMS"
      },
      {
        "id": 3,
        "name": "AMQP Port",
        "port": 5672,
        "loadBalanceProtocol": null,
        "exportName": "AMQP"
      },
      {
        "id": 4,
        "name": "STOMP Port",
        "port": 61613,
        "loadBalanceProtocol": null,
        "exportName": "STOMP"
      },
      {
        "id": 5,
        "name": "MQTT Port",
        "port": 1883,
        "loadBalanceProtocol": null,
        "exportName": "MQTT"
      },
      {
        "id": 6,
        "name": "Websocket Port",
        "port": 61614,
        "loadBalanceProtocol": null,
        "exportName": "WEBSOCKET"
      }
    ],
    "containerScripts": [

    ],
    "containerTemplates": [
      {
        "id": 1,
        "name": "Morpheus activemq config"
      }
    ],
    "environmentVariables": [

    ]
  }
}

This endpoint retrieves a specific node type.

HTTP Request

GET $serverUrl/api/library/container-types/:id

URL Parameters

Parameter Description
id ID of the node type

Create a Node Type

Use this command to create a node type.

curl -XPOST "$serverUrl/api/library/container-types" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "containerType": {
    "name": "mynode",
    "shortName": "mynode",
    "containerVersion": "1.0",
    "provisionTypeCode": "amazon",
    "scripts": [
      88
    ],
    "virtualImageId": 183,
    "mountLogs": null,
    "mountData": null,
    "statTypeCode": "amazon",
    "logTypeCode": "amazon",
    "serverType": "vm",
    "config": {
    }
  }
}'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/library/container-types

JSON Parameters

Parameter Required Description
name Y Node type name
shortName Y The short name is a name with no spaces used for display in your container list.
code N Node type code. Default is auto-generated UUID.
description N Node type description
containerVersion Y Version of the node type
provisionTypeCode Y Provision type code, eg. amazon, etc.
scripts N Array of script IDs, see Scripts
templates N Array of file template IDs, see File Templates
environmentVariables N Array of node type env variables, see Environment Variables

note The available configuration settings vary by provision type.

Environment Variable Parameters

The environmentVariables parameter is array of env objects with following fields:

Parameter Required Description
name Y Environment variable name
value N Sets fixed value for variable
masked N Can be used to enable / disable masking of variable, default is off
export N Can be used to enable / disable export of variable, default is off

Update a Node Type

Use this command to update an existing node type.

curl -XPUT "$serverUrl/api/library/container-types/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"layout": {
        "name": "Custom Node Name",
        "containerVersion": "1.2",
        "environmentVariables": [
          {
            "name": "foo",
            "value": "bar"
          }
        ],
      }}

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/container-types/:id

URL Parameters

Parameter Description
id The ID of the node type

JSON Parameters

Parameter Required Description
name Y Node type name
description N Node type description
containerVersion Y Version of the node type
provisionTypeCode Y Provision type code, eg. amazon, etc.
containerScripts N Array of script IDs, see Scripts
containerTemplates N Array of file template IDs, see File Templates
environmentVariables N Array of node type env variables, see Environment Variables

note The available configuration settings vary by provision type.

Delete a Node Type

curl -XDELETE "$serverUrl/api/library/container-types/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a node type

HTTP Request

DELETE $serverUrl/api/library/container-types/:id

URL Parameters

Parameter Description
id The ID of the node type

File Templates

Provides API interfaces for managing file templates within Morpheus.

A File Template may also be referred to as a Container Template or containerTemplate.

Get All File Templates

curl "$serverUrl/api/library/container-templates" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containerTemplates": [
    {
      "id": 83,
      "code": "b94bb003-31c4-418a-a067-562fa58d0dea",
      "account": {
        "id": 1,
        "name": "root"
      },
      "name": "testfile.txt",
      "fileName": "testfile.txt",
      "filePath": "/tmp",
      "templateType": null,
      "templatePhase": "preProvision",
      "template": "# this is a test file template\ntest:",
      "category": null,
      "settingCategory": null,
      "settingName": null,
      "autoRun": true,
      "runOnScale": false,
      "runOnDeploy": false,
      "fileOwner": null,
      "fileGroup": null,
      "permissions": null,
      "dateCreated": "2018-05-23T09:42:51Z",
      "lastUpdated": "2018-05-23T09:46:56Z"
    }
  ],
  "meta": {
    "size": 25,
    "total": 119,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all file templates.

The value of template will be masked as ************ for system owned file templates.

HTTP Request

GET $serverUrl/api/library/container-templates

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, fileName, category and settingCategory, restricts query to only load file templates which contain the phrase specified
name Name filter, restricts query to only load file template matching name specified
fileName Filename filter, restricts query to only load file template matching fileName specified

Get a Specific File Template

curl "$serverUrl/api/library/container-templates/27" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containerTemplate": {
    "id": 27,
    "code": "nginx-1.9",
    "account": null,
    "name": "Nginx Config",
    "fileName": "default.conf",
    "filePath": "/etc/nginx/conf.d",
    "templateType": null,
    "templatePhase": "preProvision",
    "template": "************",
    "category": null,
    "settingCategory": "nginx",
    "settingName": "siteConf",
    "autoRun": true,
    "runOnScale": null,
    "runOnDeploy": null,
    "fileOwner": null,
    "fileGroup": null,
    "permissions": null,
    "dateCreated": "2016-08-27T19:26:15Z",
    "lastUpdated": "2019-10-02T00:31:54Z"
  }
}

This endpoint retrieves a specific file template.

The value of template will be masked as ************ for system owned file templates.

HTTP Request

GET $serverUrl/api/library/container-templates/:id

URL Parameters

Parameter Description
id ID of the file template

Create a File Template

Use this command to create a file template.

curl -XPOST "$serverUrl/api/library/container-templates" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"containerTemplate": {
    "templatePhase": "provision",
    "name": "appconfig",
    "fileName": "appconfig.yml",
    "template": "# this is a test file template\ntest:"
  }
}'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/library/container-templates

JSON Parameters

Parameter Required Description
name Y File template name
fileName Y Filename for the file template
filePath N Path for the file template
category N Category
templatePhase N Template Phase, provision, start, etc.
template N Template content, that is, the file template content itself.
fileOwner N File Owner
settingName N Setting Name
settingCategory N Setting Category

Update a File Template

Use this command to update an existing file template.

curl -XPUT "$serverUrl/api/library/container-templates/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"containerTemplate": {
    "name":"appconfig.yml"
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/container-templates/:id

URL Parameters

Parameter Description
id The ID of the file template

JSON Parameters

Parameter Required Description
name Y File template name
fileName Y Filename for the file template
filePath N Path for the file template
category N Category
templatePhase N Template Phase, provision, start, etc.
template N Template content, that is, the file template content itself.
fileOwner N File Owner
settingName N Setting Name
settingCategory N Setting Category

Delete a File Template

curl -XDELETE "$serverUrl/api/library/container-templates/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a file template

HTTP Request

DELETE $serverUrl/api/library/container-templates/:id

URL Parameters

Parameter Description
id The ID of the file template

Scripts

Provides API interfaces for managing scripts within Morpheus.

A Script may also be referred to as a Container Script or containerScript.

Get All Scripts

curl "$serverUrl/api/library/container-scripts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containerScripts": [
     {
      "id": 10,
      "code": "cassandra-2.1-vm-start",
      "account": null,
      "name": "cassandra start",
      "category": null,
      "sortOrder": 1,
      "scriptVersion": "1.0",
      "scriptPhase": "start",
      "scriptType": "bash",
      "script": "************",
      "scriptService": null,
      "scriptMethod": null,
      "runAsUser": null,
      "runAsPassword": null,
      "sudoUser": true,
      "failOnError": true
    },
    {
      "id": 9,
      "code": "cassandra-2.1-vm-stop",
      "account": null,
      "name": "cassandra stop",
      "category": null,
      "sortOrder": 1,
      "scriptVersion": "1.0",
      "scriptPhase": "stop",
      "scriptType": "bash",
      "script": "************",
      "scriptService": null,
      "scriptMethod": null,
      "runAsUser": null,
      "runAsPassword": null,
      "sudoUser": true,
      "failOnError": true
    },
  ],
  "meta": {
    "size": 25,
    "total": 200,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all scripts.

The value of script will be masked as ************ for system owned scripts.

HTTP Request

GET $serverUrl/api/library/container-scripts

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, restricts query to only load scripts which contain the phrase specified
scriptType Script type code filter, restricts query to only load scripts of specified type
scriptPhase Script phase filter, restricts query to only load scripts of specified phase

Get a Specific Script

curl "$serverUrl/api/library/container-scripts/10" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containerScript": {
    "id": 10,
    "code": "cassandra-2.1-vm-start",
    "account": null,
    "name": "cassandra start",
    "category": null,
    "sortOrder": 1,
    "scriptVersion": "1.0",
    "scriptPhase": "start",
    "scriptType": "bash",
    "script": "************",
    "scriptService": null,
    "scriptMethod": null,
    "runAsUser": null,
    "runAsPassword": null,
    "sudoUser": true,
    "failOnError": true
  }
}

This endpoint retrieves a specific script.

The value of script will be masked as ************ for system owned scripts.

HTTP Request

GET $serverUrl/api/library/container-scripts/:id

URL Parameters

Parameter Description
id ID of the script

Create a Script

Use this command to create a script.

curl -XPOST "$serverUrl/api/library/container-scripts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"containerScript": {
    "scriptType": "bash",
    "scriptPhase": "provision",
    "script": "echo hello > /tmp/hello.txt",
    "name": "hello"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "containerScript": {
    "id": 100
  }
}

HTTP Request

POST $serverUrl/api/library/container-scripts

JSON Parameters

Parameter Required Description
name Y Script name
category N Script category
scriptVersion N Version of the script. Default is 1.
scriptPhase N Phase for the script, provision, start, etc.
scriptType N Type for the script, bash or powershell. Default is bash.
script N Script content, that is, the code itself.
runAsUser N Run as a specific user.
sudoUser N Sudo, whether or not to run with sudo. Default is false.

Update a Script

Use this command to update an existing script.

curl -XPUT "$serverUrl/api/library/container-scripts/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"containerScript": {
    "script": "echo 'hello world' > /tmp/hello.txt",
  }
}'

The above command returns JSON structured like this:

{
  "success": true,
  "containerScript": {
    "id": 100
  }
}

HTTP Request

PUT $serverUrl/api/library/container-scripts/:id

URL Parameters

Parameter Description
id The ID of the script

JSON Parameters

Parameter Required Description
name Y Script name
category N Script category
scriptVersion N Version of the script. Default is 1.
scriptPhase N Phase for the script, provision, start, etc.
scriptType N Type for the script, bash or powershell. Default is bash.
script N Script content, that is, the code itself.
runAsUser N Run as a specific user.
sudoUser N Sudo, whether or not to run with sudo. Default is false.

Delete a Script

curl -XDELETE "$serverUrl/api/library/container-scripts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a script

HTTP Request

DELETE $serverUrl/api/library/container-scripts/:id

URL Parameters

Parameter Description
id The ID of the script

Option Types

Provides API interfaces for managing Library: Option Types within Morpheus.

Get All Option Types

curl "$serverUrl/api/library/option-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "optionTypes": [
    {
      "id": 811,
      "name": "DB Version",
      "description": "Database Version",
      "code": null,
      "fieldName": "dbVersion",
      "fieldLabel": "DB Version",
      "fieldContext": "config.customOptions",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "placeHolder": "yourversion",
      "helpBlock": null,
      "defaultValue": null,
      "optionSource": null,
      "optionList": null,
      "type": "text",
      "advanced": false,
      "required": false,
      "editable": false,
      "creatable": true,
      "config": {
      },
      "displayOrder": 0,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": false,
      "dependsOnCode": null,
      "contextualDefault": false
    },
    {
      "id": 1236,
      "name": "myselect",
      "description": "a select option type",
      "code": "myselect",
      "fieldName": "myselect",
      "fieldLabel": "My Select",
      "fieldContext": "config.customOptions",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "placeHolder": null,
      "helpBlock": null,
      "defaultValue": null,
      "optionSource": "list",
      "optionList": {
        "id": 51,
        "name": "my groups"
      },
      "type": "select",
      "advanced": false,
      "required": false,
      "editable": false,
      "creatable": true,
      "config": {
      },
      "displayOrder": 3,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": false,
      "dependsOnCode": null,
      "contextualDefault": false
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all option types.

HTTP Request

GET $serverUrl/api/library/option-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, code or description, restricts query to only load option types which contain the phrase specified
name Name filter, restricts query to only load type matching name specified
code Code filter, restricts query to only load type matching code specified
fieldName Field Name filter, restricts query to only load type matching fieldName specified
fieldContext Field Context filter, restricts query to only load type matching fieldContext specified
fieldLabel Field Label filter, restricts query to only load type matching fieldLabel specified

Get a Specific Option Type

curl "$serverUrl/api/library/option-types/811" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "optionType": {
    "id": 811,
    "name": "DB Version",
    "description": "Database Version",
    "code": null,
    "fieldName": "dbVersion",
    "fieldLabel": "DB Version",
    "fieldContext": "config.customOptions",
    "fieldGroup": null,
    "fieldClass": null,
    "fieldAddOn": null,
    "fieldComponent": null,
    "placeHolder": "yourversion",
    "helpBlock": null,
    "defaultValue": null,
    "optionSource": null,
    "optionList": null,
    "type": "text",
    "advanced": false,
    "required": false,
    "editable": false,
    "creatable": true,
    "config": {
    },
    "displayOrder": 0,
    "wrapperClass": null,
    "enabled": true,
    "noBlank": false,
    "dependsOnCode": null,
    "contextualDefault": false
  }
}

This endpoint retrieves a specific option type.

HTTP Request

GET $serverUrl/api/library/option-types/:id

URL Parameters

Parameter Description
id ID of the option type

Create an Option Type

Use this command to create an option type.

curl -XPOST "$serverUrl/api/library/option-types" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"optionType": {
       "name": "Test Input",
       "type": "text",
       "description": "A test option type",
       "fieldName": "testinput",
       "fieldLabel": "Test Input"
     }}'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/library/option-types

JSON Parameters

Parameter Required Description
name Y Name
description N Description
fieldName N Field Name, the name for user input. This along with fieldContext determines the configuration property name.
type N Type, the type of input. eg. text, checkbox, select, etc. Default is text.
fieldLabel N Field Label, the label for user input.
placeHolder N Placeholder
defaultValue N Default Value
required N Required, Default is false.
exportMeta N Export as Tag, Default is false.
optionList.id N ID of Option List. For use with type select, this will set optionSource to list.

Update an Option Type

Use this command to update an existing option type.

curl -XPUT "$serverUrl/api/library/option-types/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"optionType": {
        "description": "An example input"
      }}

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/option-types/:id

URL Parameters

Parameter Description
id The ID of the option type

JSON Parameters

Parameter Required Description
name Y Name
description N Description
fieldName N Field Name, the name for user input. This along with fieldContext determines the configuration property name.
type N Type, the type of input. eg. text, checkbox, select, etc. Default is text.
fieldLabel N Field Label, the label for user input.
placeHolder N Placeholder
defaultValue N Default Value
required N Required, Default is false.
exportMeta N Export as Tag, Default is false.
optionList.id N ID of Option List. For use with type select, this will set optionSource to list.

Delete an Option Type

curl -XDELETE "$serverUrl/api/library/option-types/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete an option type

HTTP Request

DELETE $serverUrl/api/library/option-types/:id

URL Parameters

Parameter Description
id The ID of the option type

Option Lists

Provides API interfaces for managing option lists within Morpheus.

An Option List may also be referred to as an Option Type List or optionTypeList.

Get All Option Lists

curl "$serverUrl/api/library/option-type-lists" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "optionTypeLists": [
    {
      "id": 32,
      "name": "mylist",
      "description": "My List",
      "type": "manual",
      "sourceUrl": null,
      "sourceMethod": "GET",
      "apiType": null,
      "ignoreSSLErrors": false,
      "realTime": false,
      "visibility": "private",
      "config": {
      },
      "initialDataset": "foo,Foo\nbar,Bar\nbaz,Baz\nhello,world",
      "translationScript": null,
      "requestScript": null,
      "account": {
        "id": 1,
        "name": "morpheusdata.com"
      }
    },
    {
      "id": 56,
      "name": "group1 clouds",
      "description": null,
      "type": "rest",
      "sourceUrl": "http://10.0.2.2:8080/api/options/clouds?groupId=1",
      "sourceMethod": "GET",
      "apiType": null,
      "ignoreSSLErrors": false,
      "realTime": false,
      "visibility": "private",
      "config": {
        "sourceHeaders": [
          {
            "name": "Authorization",
            "value": "************",
            "masked": "on"
          }
        ]
      },
      "initialDataset": null,
      "translationScript": "for(var x=0;x < data.data.length; x++) {\n    results.push(data.data[x]);\n}",
      "requestScript": null,
      "account": {
        "id": 1,
        "name": "morpheusdata.com"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all option lists.

HTTP Request

GET $serverUrl/api/library/option-type-lists

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name or description filter, restricts query to only load option lists which contain the phrase specified
name Name filter, restricts query to only load option list of specified name

Get a Specific Option List

curl "$serverUrl/api/library/option-type-lists/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "optionTypeList": {
    "id": 1,
    "name": "my groups",
    "description": "A list of my groups",
    "type": "rest",
    "sourceUrl": "http://myapp/api/options/groups",
    "sourceMethod": "GET",
    "ignoreSSLErrors": false,
    "realTime": false,
    "visibility": "private",
    "config": {
      "sourceHeaders": [
        {
          "name": "Authorization",
          "value": "Bearer 8af52d52-c05d-1e3f-ae8b-542ecf47ae10",
          "masked": false
        },
        {
          "name": "Foobar",
          "value": "************",
          "masked": true
        }
      ]
    },
    "initialDataset": null,
    "translationScript": "for(var x=0;x < data['data'].length; x++) {\r\n    results.push(data.data[x]);\r\n}",
    "requestScript": null,
    "account": {
      "id": 1,
      "name": "morpheusdata.com"
    }
  }
}

This endpoint retrieves a specific option list.

HTTP Request

GET $serverUrl/api/library/option-type-lists/:id

URL Parameters

Parameter Description
id ID of the option list

List Items for a Specific Option List

curl "$serverUrl/api/library/option-type-lists/1/items" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "listItems": [
    {
      "name": "foo",
      "value": "Foo"
    },
    {
      "name": "bar",
      "value": "Bar"
    },
    {
      "name": "baz",
      "value": "Baz"
    },
    {
      "name": "hello",
      "value": "world"
    }
  ]
}

This endpoint retrieves the items for a specific option list.

HTTP Request

GET $serverUrl/api/library/option-type-lists/:id/items

URL Parameters

Parameter Description
id ID of the option list

Create an Option List

Use this command to create an option list.

curl -XPOST "$serverUrl/api/library/option-type-lists" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "optionTypeList": {
    "name": "resty",
    "description": "A resty list",
    "type": "rest",
    "sourceUrl": "$serverUrl/api/options/mydata",
    "sourceMethod": "GET",
    "ignoreSSLErrors": true,
    "realTime": false,
    "visibility": "private",
    "initialDataset": null,
    "translationScript": null,
    "config": {
      "sourceHeaders": [
        {
          "name": "Authorization",
          "value": "Bearer foobar-key",
          "masked": true
        }
      ]
    }
  }
}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/library/option-type-lists

JSON Parameters

Parameter Required Description
name Y Name
description N Description
type N Option List Type eg. rest api or manual. Default is rest.
sourceUrl N Source URL, the http(s) URL to request data from. Required when type is rest.
visibility N Visibility. Default is private.
sourceMethod N Source Method, the HTTP method. Default is GET.
apiType N Api Type, The code of the api option list to use, eg. clouds, environments, groups, instances, instance-wiki, networks, servicePlans, resourcePools, securityGroups, servers, server-wiki. Required when type is api.
ignoreSSLErrors N Ignore SSL Errors. Default is false.
realTime N Real Time. Default is false.
initialDataset N Initial Dataset. Create an initial JSON or CSV dataset to be used as the collection for this option list. It should be a list containing objects with properties 'name’, and 'value’. Required when type is manual.
translationScript N Translation Script. Create a js script to translate the result data object into an Array containing objects with properties 'name’ and 'value’. The input data is provided as data and the result should be put on the global variable results.
requestScript N Request Script. Create a js script to prepare the request. Return a data object as the body for a post, and return an array containing properties 'name’ and 'value’ for a get. The input data is provided as data and the result should be put on the global variable results.
config.sourceHeaders N Array of source headers to use when requesting data., see Source Headers

Source Headers

The config.sourceHeaders parameter is array of objects with following fields:

Parameter Required Description
name Y Header name
value N Header value
masked N Can be used to enable / disable masking of value, default is off

Update an Option List

Use this command to update an existing option list.

curl -XPUT "$serverUrl/api/library/option-type-lists/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "optionTypeList": {
    "name": "resty things",
    "description": " resty list",
    "sourceUrl": "http://myapp/api/options/things",
    "sourceMethod": "GET",
    "type": "rest",
    "config": {
      "sourceHeaders": [
        {
          "name": "Authorization",
          "value": "Bearer foobar-baz-key",
          "masked": true
        }
      ]
    }
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/option-type-lists/:id

URL Parameters

Parameter Description
id The ID of the option list

JSON Parameters

Parameter Required Description
name Y Name
description N Description
type N Option List Type eg. rest api or manual. Default is rest.
sourceUrl N Source URL, the http(s) URL to request data from. Required when type is rest.
visibility N Visibility. Default is private.
sourceMethod N Source Method, the HTTP method. Default is GET.
apiType N Api Type, The code of the api list to use, eg. clouds, groups, etc. Required when type is api.
ignoreSSLErrors N Ignore SSL Errors. Default is false.
realTime N Real Time. Default is false.
initialDataset N Initial Dataset. Create an initial JSON or CSV dataset to be used as the collection for this option list. It should be a list containing objects with properties 'name’, and 'value’.
translationScript N Translation Script. Create a js script to translate the result data object into an Array containing objects with properties 'name’ and 'value’. The input data is provided as data and the result should be put on the global variable results.
requestScript N Request Script. Create a js script to prepare the request. Return a data object as the body for a post, and return an array containing properties 'name’ and 'value’ for a get. The input data is provided as data and the result should be put on the global variable results.
config.sourceHeaders N Array of source headers to use when requesting data., see Source Headers

Delete an Option List

curl -XDELETE "$serverUrl/api/library/option-type-lists/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete an option list.

HTTP Request

DELETE $serverUrl/api/library/option-type-lists/:id

URL Parameters

Parameter Description
id The ID of the option list

Options

Morpheus has several objects that have dynamic models depending on the type of the object. This includes options when provisioning different instances or even options when defining tasks or creating docker hosts!. This section aims to describe what is contained in the option-types association as well as how to query for available options in certain option-type scenarios.

Example of an Option Type Record

{
    "optionTypes": [
                {
                    "name": "subnet",
                    "description": null,
                    "fieldName": "subnetId",
                    "fieldLabel": "Subnet",
                    "fieldContext": "config",
                    "fieldAddOn": null,
                    "placeHolder": null,
                    "helpBlock": "",
                    "defaultValue": null,
                    "optionSource": "amazonSubnet",
                    "type": "select",
                    "advanced": false,
                    "required": true,
                    "editable": false,
                    "config": [],
                    "displayOrder": 100
                },
                {
                    "name": "security group",
                    "description": null,
                    "fieldName": "securityId",
                    "fieldLabel": "Security Group",
                    "fieldContext": "config",
                    "fieldAddOn": null,
                    "placeHolder": null,
                    "helpBlock": "",
                    "defaultValue": null,
                    "optionSource": "amazonSecurityGroup",
                    "type": "select",
                    "advanced": false,
                    "required": true,
                    "editable": false,
                    "config": [],
                    "displayOrder": 101
                },
                {
                    "name": "public key",
                    "description": null,
                    "fieldName": "publicKeyId",
                    "fieldLabel": "Public Key",
                    "fieldContext": "config",
                    "fieldAddOn": null,
                    "placeHolder": null,
                    "helpBlock": "",
                    "defaultValue": null,
                    "optionSource": "keyPairs",
                    "type": "select",
                    "advanced": false,
                    "required": false,
                    "editable": false,
                    "config": [],
                    "displayOrder": 9
                }
            ]
}

Option types can easily represent some common input types, including text, number, radio, checkbox, and dropdown/multiple choice.

JSON Parameters

Parameter Description
name The name of the option type for handy reference
description Short description of the option type (the CLI actually shows this when pressing ? for help)
fieldName The property key for when posting this option type to a JSON POST request
fieldLabel User friendly label for prompting a user for input
fieldContext Some properties need nested i.e. in a config: {} block. This is a . separated context of where the property should be constructed
placeHolder Any placeholder text when nothing is yet entered
helpBlock Short help text describing the option
defaultValue The default value if no user entry is specified. This value should be passed to the desired JSON Map if nothing else is entered
optionSource Option source references an API endpoint for receiving a JSON list of available options for this field.
type The type of input. I.e. text, select, radio,checkbox, etc.
required Is this field entry required for the request
editable Used primarily on tasks and workflows. Basically wether or not the field can be overridden optionally when the object is run
displayOrder The order with which the fields should be prompted. This is rather important when using optionSource in some scenarios for determining available values.
config: Any special configuration options pertaining to specific input types, like a radio button.

Get Option Source Data

curl "$serverUrl/api/options/keyPairs"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

[
    {"name": "My Key Pair", "value": 1}
]

HTTP Request

GET $serverUrl/api/options/:optionSource

Returns a list of name/value pairs for option-type models. Some option-types depend on input data for proper representation. This typically includes zoneId or siteId for the item being provisioned as request parameters or sometimes previous option type parameters. Each option returned has a value, which is often the id, but may be a code or other attribute.

List Options For Code Repositories

curl "$serverUrl/api/options/codeRepositories"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like the standard Get Option Source Data

HTTP Request

GET $serverUrl/api/options/codeRepositories

Returns a list code repositories, which are a certain type of integration.

Spec Templates

Provides API interfaces for managing spec templates within Morpheus.

Get All Spec Templates

curl "$serverUrl/api/library/spec-templates" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "specTemplates": [
    {
      "id": 1,
      "account": {
        "id": 1,
        "name": "root"
      },
      "name": "cftest",
      "code": null,
      "type": {
        "id": 5,
        "name": "CloudFormation Template",
        "code": "cloudFormation"
      },
      "externalId": null,
      "externalType": null,
      "deploymentId": null,
      "status": null,
      "file": {
        "id": 11,
        "sourceType": "local",
        "contentRef": null,
        "contentPath": null,
        "repository": null,
        "content": "#my config"
      },
      "config": {
        "cloudformation": {
          "IAM": false,
          "CAPABILITY_NAMED_IAM": false,
          "CAPABILITY_AUTO_EXPAND": false
        }
      },
      "createdBy": "admin",
      "updatedBy": null,
      "dateCreated": "2020-01-11T04:37:12+0000",
      "lastUpdated": "2020-01-11T04:37:12+0000"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all spec templates.

HTTP Request

GET $serverUrl/api/library/spec-templates

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, description and provision type name, restricts query to only load spec templates which contain the phrase specified
name Name filter, restricts query to only load template matching name specified

Get a Specific Spec Template

curl "$serverUrl/api/library/spec-templates/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "specTemplate": {
    "id": 13,
    "account": {
      "id": 1,
      "name": "root"
    },
    "name": "cache-cluster",
    "code": null,
    "type": {
      "id": 5,
      "name": "CloudFormation Template",
      "code": "cloudFormation"
    },
    "externalId": null,
    "externalType": null,
    "deploymentId": null,
    "status": null,
    "file": {
      "id": 13,
      "sourceType": "local",
      "contentRef": null,
      "contentPath": null,
      "repository": null,
      "content": "{\n  \"AWSTemplateFormatVersion\" : \"2010-09-09\",\n\n  \"Description\" : \"AWS CloudFormation Sample Template ElastiCache: Sample template showing how to create an Amazon ElastiCache Cache Cluster with Auto Discovery. **WARNING** This template creates an Amazon ElastiCache Cluster. You will be billed for the AWS resources used if you create a stack from this template.\",\n\n  \"Parameters\" : {\n\n    \"CacheNodeType\" : {\n      \"Description\" : \"The compute and memory capacity of the nodes in the Cache Cluster\",\n      \"Type\" : \"String\",\n      \"Default\" : \"cache.t2.small\",\n      \"AllowedValues\" : [ \"cache.m1.small\", \"cache.m1.large\", \"cache.m1.xlarge\", \"cache.m2.xlarge\", \"cache.m2.2xlarge\", \"cache.m2.4xlarge\", \"cache.c1.xlarge\", \"cache.t2.micro\", \"cache.t2.small\", \"cache.t2.medium\", \"cache.m3.medium\", \"cache.m3.large\", \"cache.m3.xlarge\", \"cache.m3.2xlarge\", \"cache.r3.large\", \"cache.r3.xlarge\", \"cache.r3.2xlarge\", \"cache.r3.4xlarge\", \"cache.r3.8xlarge\" ]\n,\n      \"ConstraintDescription\" : \"must select a valid Cache Node type.\"\n    },\n\n    \"NumberOfCacheNodes\" : {\n      \"Default\": \"1\",\n      \"Description\" : \"The number of Cache Nodes the Cache Cluster should have\",\n      \"Type\": \"Number\",\n      \"MinValue\": \"1\",\n      \"MaxValue\": \"10\",\n      \"ConstraintDescription\" : \"must be between 5 and 10.\"\n    }\n  },\n\n  \"Resources\" : {\n\n    \"CacheCluster\" : {\n      \"Type\": \"AWS::ElastiCache::CacheCluster\",\n      \"Properties\": {\n        \"CacheNodeType\"           : { \"Ref\" : \"CacheNodeType\" },\n        \"CacheSecurityGroupNames\" : [ { \"Ref\" : \"CacheSecurityGroup\" } ],\n        \"Engine\"                  : \"memcached\",\n        \"NumCacheNodes\"           : { \"Ref\" : \"NumberOfCacheNodes\" }\n      }\n    },\n\n    \"CacheSecurityGroup\": {\n      \"Type\": \"AWS::ElastiCache::SecurityGroup\",\n      \"Properties\": {\n        \"Description\"  : \"Lock cache down to Web Server access only\"\n      }\n    }\n  }\n}\n"
    },
    "config": {
    },
    "createdBy": "admin",
    "updatedBy": "admin",
    "dateCreated": "2020-01-11T15:47:18+0000",
    "lastUpdated": "2020-01-11T15:47:18+0000"
  }
}

This endpoint retrieves a specific spec template.

HTTP Request

GET $serverUrl/api/library/spec-templates/:id

URL Parameters

Parameter Description
id ID of the spec template

Create a Spec Template

Use this command to create a spec template.

curl -XPOST "$serverUrl/api/library/spec-templates" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "specTemplate": {
    "name": "cftest",
    "type": {
      "code": "cloudFormation"
    },
    "config": {
      "cloudformation": {
        "IAM": "on",
        "CAPABILITY_NAMED_IAM": "on",
        "CAPABILITY_AUTO_EXPAND": "off"
      }
    },
    "file": {
      "sourceType": "local",
      "content": "{\"test\":\"spec\"}"
    }
  }
}'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/library/spec-templates

JSON Parameters

Parameter Required Description
name Y Spec template name
type.code Y Spec Template Type. i.e. arm, cloudFormation, helm, kubernetes, oneview, terraform, ucs.
file Y File, object specifying file type and content, see File Object

File Object Parameter

Parameter Required Description
sourceType Y File Source i.e. local, repository, url. Default is local.
content Y File content, the template text. Only required when sourceType is local.
contentPath Y Content Path, the repo file location or url. Required when sourceType is repository or url.
contentRef N Content Ref, the branch/tag. Only used when sourceType is repo.
repository.id N Code Repository ID, required for type repository. Use /api/options/codeRepositories to see available repositories.

Cloud Formation Capability Parameters

The Cloud Formation type supports some additional configuration parameters:

Parameter Required Description
config.cloudformation.IAM Y CAPABILITY_IAM
config.cloudformation.CAPABILITY_NAMED_IAM Y CAPABILITY_NAMED_IAM
config.cloudformation.CAPABILITY_AUTO_EXPAND Y CAPABILITY_AUTO_EXPAND

Update a Spec Template

Use this command to update an existing spec template.

curl -XPUT "$serverUrl/api/library/spec-templates/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"specTemplate": {
        "name": "cftest2"
      }}

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/spec-templates/:id

URL Parameters

Parameter Description
id The ID of the spec template

JSON Parameters

Parameter Required Description
name Y Spec template name
type.code Y Spec Template Type. i.e. arm, cloudFormation, helm, kubernetes, oneview, terraform, ucs.
file Y File, object specifying file type and content, see File Object

Delete a Spec Template

curl -XDELETE "$serverUrl/api/library/spec-templates/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a spec template

HTTP Request

DELETE $serverUrl/api/library/spec-templates/:id

URL Parameters

Parameter Description
id The ID of the spec template

Cluster Layouts

Provides API interfaces for managing cluster layouts within Morpheus.

Get All Cluster Layouts

curl "$serverUrl/api/library/cluster-layouts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "layouts": [
    {
      "id": 1,
      "optionTypes": [
        {
          "id": 1080,
          "name": "Option 2",
          "code": "option2",
          "description": null,
          "fieldName": "option2",
          "fieldLabel": "Option 2",
          "fieldContext": "config.customOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "placeHolder": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "optionList": null,
          "type": "checkbox",
          "advanced": false,
          "required": false,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 0,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        }
      ],
      "serverCount": 1,
      "dateCreated": "2019-07-23T00:38:25+0000",
      "code": "docker-fusion-ubuntu-16.04-single",
      "lastUpdated": "2019-10-21T20:39:54+0000",
      "hasAutoScale": true,
      "memoryRequirement": 1073741824,
      "actions": [

      ],
      "installContainerRuntime": true,
      "computeServers": [
        {
          "id": 1,
          "priorityOrder": 0,
          "nodeCount": 1,
          "nodeType": "worker",
          "minNodeCount": null,
          "maxNodeCount": null,
          "dynamicCount": true,
          "name": "docker host",
          "code": "docker-fusion-ubuntu-16.04-set",
          "category": "ubuntu",
          "config": null,
          "containerType": {
            "id": 1106,
            "account": null,
            "name": "Docker Ubuntu 16.04",
            "shortName": "ubuntu",
            "containerVersion": "16.04",
            "provisionType": {
              "id": 19,
              "name": "Fusion",
              "code": "fusion"
            },
            "virtualImage": {
              "id": 204,
              "name": "Morpheus Ubuntu 16.04.3 v1"
            },
            "category": "ubuntu",
            "config": {
            },
            "containerPorts": [
              {
                "id": 7,
                "name": "SSH",
                "port": 22,
                "loadBalanceProtocol": null,
                "exportName": "SSH"
              }
            ],
            "containerScripts": [

            ],
            "containerTemplates": [

            ],
            "environmentVariables": [

            ]
          },
          "computeServerType": {
            "id": 119,
            "code": "fusionLinux",
            "name": "Fusion Docker Host",
            "managed": true,
            "externalDelete": true
          },
          "provisionService": null,
          "planCategory": null,
          "namePrefix": null,
          "nameSuffix": null,
          "forceNameIndex": null,
          "loadBalance": false
        }
      ],
      "computeVersion": "16.04",
      "provisionType": {
        "id": 19,
        "name": "Fusion",
        "code": "fusion"
      },
      "hasSettings": false,
      "sortOrder": 5,
      "taskSets": [

      ],
      "environmentVariables": [
        {
          "evarName": "foo",
          "name": "foo",
          "defaultValue": "bar",
          "valueType": "fixed",
          "export": false,
          "masked": false
        }
      ],
      "hasConfig": false,
      "groupType": {
        "id": 2,
        "code": "docker-cluster",
        "name": "Docker Cluster"
      },
      "name": "Docker on Ubuntu 16.04",
      "type": {
        "id": 119,
        "code": "fusionLinux",
        "name": "Fusion Docker Host"
      },
      "creatable": true,
      "specTemplates": [

      ],
      "enabled": true,
      "description": "This will provision a single docker host vm in fusion"
    }
  ],
  "meta": {
    "size": 1,
    "total": 84,
    "offset": 0,
    "max": 1
  }
}

This endpoint retrieves all cluster layouts.

HTTP Request

GET $serverUrl/api/library/cluster-layouts

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, description and provision type name, restricts query to only load cluster layouts which contain the phrase specified
provisionType Provision type code filter, restricts query to only load cluster layouts of specified provision type

Get a Specific Cluster Layout

curl "$serverUrl/api/library/cluster-layouts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "layout": {
    "id": 1,
    "optionTypes": [

    ],
    "serverCount": 1,
    "dateCreated": "2019-07-23T00:38:25+0000",
    "code": "docker-fusion-ubuntu-16.04-single",
    "lastUpdated": "2019-10-21T20:39:54+0000",
    "hasAutoScale": true,
    "memoryRequirement": 1073741824,
    "actions": [

    ],
    "installContainerRuntime": true,
    "computeServers": [
      {
        "id": 1,
        "priorityOrder": 0,
        "nodeCount": 1,
        "nodeType": "worker",
        "minNodeCount": null,
        "maxNodeCount": null,
        "dynamicCount": true,
        "name": "docker host",
        "code": "docker-fusion-ubuntu-16.04-set",
        "category": "ubuntu",
        "config": null,
        "containerType": {
          "id": 1106,
          "account": null,
          "name": "Docker Ubuntu 16.04",
          "shortName": "ubuntu",
          "containerVersion": "16.04",
          "provisionType": {
            "id": 19,
            "name": "Fusion",
            "code": "fusion"
          },
          "virtualImage": {
            "id": 204,
            "name": "Morpheus Ubuntu 16.04.3 v1"
          },
          "category": "ubuntu",
          "config": {
          },
          "containerPorts": [
            {
              "id": 7,
              "name": "SSH",
              "port": 22,
              "loadBalanceProtocol": null,
              "exportName": "SSH"
            }
          ],
          "containerScripts": [

          ],
          "containerTemplates": [

          ],
          "environmentVariables": [

          ]
        },
        "computeServerType": {
          "id": 119,
          "code": "fusionLinux",
          "name": "Fusion Docker Host",
          "managed": true,
          "externalDelete": true
        },
        "provisionService": null,
        "planCategory": null,
        "namePrefix": null,
        "nameSuffix": null,
        "forceNameIndex": null,
        "loadBalance": false
      }
    ],
    "computeVersion": "16.04",
    "provisionType": {
      "id": 19,
      "name": "Fusion",
      "code": "fusion"
    },
    "hasSettings": false,
    "sortOrder": 5,
    "taskSets": [

    ],
    "environmentVariables": [

    ],
    "hasConfig": false,
    "groupType": {
      "id": 2,
      "code": "docker-cluster",
      "name": "Docker Cluster"
    },
    "name": "Docker on Ubuntu 16.04",
    "type": {
      "id": 119,
      "code": "fusionLinux",
      "name": "Fusion Docker Host"
    },
    "creatable": true,
    "specTemplates": [

    ],
    "enabled": true,
    "description": "This will provision a single docker host vm in fusion"
  }
}

This endpoint retrieves a specific cluster layout.

HTTP Request

GET $serverUrl/api/library/cluster-layouts/:id

URL Parameters

Parameter Description
id ID of the cluster layout

Create a Cluster Layout

Use this command to create a cluster layout.

curl -XPOST "$serverUrl/api/library/cluster-layouts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"layout": {
       "name": "Stubby Toes Docker Cluster",
       "computeVersion": "2.2",
       "description": null,
       "creatable": true,
       "groupType": {
         "id": 2
       },
       "provisionType": {
         "id": 6
       },
       "memoryRequirement": 1073741824,
       "taskSets": [
         {
           "id": 3
         }
       ],
       "hasAutoScale": true,
       "environmentVariables": [
         {
           "name": "foo",
           "value": "bar",
           "masked": false,
           "export": false
         }
       ],
       "optionTypes": [

       ],
       "masters": [

       ],
       "workers": [
         {
           "count": 3,
           "containerType": {
             "id": 1076
           }
         }
       ]
     }}'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/library/cluster-layouts

JSON Parameters

Parameter Required Description
name Y Cluster layout name
description N Cluster layout description
computeVersion Y Version of the cluster layout
creatable N Can be used to enable / disable the creatability of the cluster layout. Default is on
hasAutoScale N Can be used to enable / disable the horizontal scaling. Default is off
installContainerRuntime N Install Docker (container runtime). Default is off
memoryRequirement N Memory requirement in bytes
groupType.id Y Cluster type ID
provisionType.id Y Provision type ID
optionTypes N Array of cluster layout option types, see Option Types
taskSets N Array of cluster layout task sets, see Task Sets
environmentVariables N Array of cluster layout env variables, see Environment Variables
masters N Array of cluster layout master nodes, see Nodes
workers N Array of cluster layout worker nodes, see Nodes

Option Types

The optionTypes parameter is array of objects with id field: json "optionTypes": [{"id":1}, {"id":2}]

Parameter Required Description
id Y ID of option type

Task Sets

The taskSets parameter is array of objects with id field, currently only supports single item: json "taskSets": [{"id":1}]

Parameter Required Description
id Y ID of task set

Environment Variables

The environmentVariables parameter is array of env objects with following fields:

Parameter Required Description
name Y Environment variable name
value N Sets fixed value for variable
masked N Can be used to enable / disable masking of variable, default is off
export N Can be used to enable / disable export of variable, default is off

Nodes

The masters and workers parameters are array of node objects with following fields:

Parameter Required Description
count N Number of nodes, defaults to 1
containerType.id Y Container type ID

Update a Cluster Layout

Use this command to update an existing cluster layout.

curl -XPUT "$serverUrl/api/library/cluster-layouts/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"layout": {
        "name": "Cluster Name",
        "description": "Cluster description",
        "computeVersion": "1.2",
        "creatable": false,
        "memoryRequirement": 1073741824,
        "hasAutoScale": true,
        "environmentVariables": [
          {
            "name": "foo",
            "value": "bar"
          }
        ],
        "groupType": {
          "id": 1
        },
        "provisionType": {
          "id": 6
        },
        "taskSets": [
          {
            "id": 3
          }
        ],
        "optionTypes": [
          {
            "id": 1079
          },
          {
            "id": 1080
          }
        ],
        "masters": [
          {
            "count": 1,
            "containerType": {
              "id": 1080
            }
          }
        ],
        "workers": [
          {
            "count": 2,
            "containerType": {
              "id": 48
            }
          }
        ]
      }}

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/library/cluster-layouts/:id

URL Parameters

Parameter Description
id The ID of the cluster layout

JSON Parameters

Parameter Required Description
name Y Cluster layout name
description N Cluster layout description
computeVersion Y Version of the cluster layout
creatable N Can be used to enable / disable the creatability of the cluster layout. Default is on
hasAutoScale N Can be used to enable / disable the horizontal scaling. Default is off
installContainerRuntime N Install Docker (container runtime).
memoryRequirement N Memory requirement in bytes
groupType.id Y Cluster type ID
provisionType.id Y Provision type ID
optionTypes N Array of cluster layout option types, see Option Types
taskSets N Array of cluster layout task sets, see Task Sets
environmentVariables N Array of cluster layout env variables, see Environment Variables
masters N Array of cluster layout master nodes, see Nodes
workers N Array of cluster layout worker nodes, see Nodes

Clone a Cluster Layout

Use this command to clone a cluster layout.

curl -XPOST "$serverUrl/api/library/cluster-layouts/7/clone" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/library/cluster-layouts/:id/clone

Query Parameters

Parameter Required Description
name N Name of cluster layout. Defaults to Copy of <cloned layout name>
description N Description of cluster layout. Defaults to cloned layout description
computeVersion N Version of cluster layout. Defaults to cloned layout version

Delete a Cluster Layout

curl -XDELETE "$serverUrl/api/library/cluster-layouts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a cluster layout

HTTP Request

DELETE $serverUrl/api/library/cluster-layouts/:id

URL Parameters

Parameter Description
id The ID of the cluster layout

Deployments

Provides API to manage “Deployment archives” for use with deployable instance types (i.e. Tomcat, Nginx, Apache, etc.). A deployment can have many versions and each version is its own archive of files. A deployment version may be a collection of uploaded files or it may just be a reference to an external git repository or arbitrary url. Deployment versions are used in instance deploys.

Get All Deployments

curl "$serverUrl/api/deployments" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "deployments": [
    {
      "id": 1,
      "name": "example-deployment",
      "description": null,
      "accountId": 1,
      "externalId": null,
      "dateCreated": "2020-09-10T18:58:55+0000",
      "lastUpdated": "2020-09-10T18:62:51+0000",
      "versionCount": 1
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint returns a paginated list of deployments.

HTTP Request

GET $serverUrl/api/deployments

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Filter by wildcard search of name and description
name Filter by name
description Filter by description
dateCreated Filter by dateCreated, the created timestamp is more recent or equal to the date specified
lastUpdated Filter by lastUpdated, the last modified timestamp is more recent or equal to the date specified

Get a Specific Deployment

curl "$serverUrl/api/deployments/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "deployment": {
    "id": 1,
    "name": "example-deployment",
    "description": "Example deployment",
    "accountId": 1,
    "externalId": null,
    "dateCreated": "2020-09-10T18:58:55+0000",
    "lastUpdated": "22020-09-10T18:58:55+0000",
    "versionCount": 1,
    "versions": [
      {
        "id": 1,
        "deployType": "file",
        "fetchUrl": null,
        "gitUrl": null,
        "gitRef": null,
        "userVersion": "1.0",
        "version": "1.0",
        "status": "created",
        "dateCreated": "2020-09-10T19:56:36+0000",
        "lastUpdated": "2020-09-10T19:56:36+0000"
      }
    ]
  }
}

This endpoint retrieves a specific deployment. By default the 5 most recent versions are returned, more can be returned by specifying the maxVersions parameter.

HTTP Request

GET $serverUrl/api/deployments/:id

URL Parameters

Parameter Description
id The ID of the deployment

Query Parameters

Parameter Default Description
maxVersions 5 Max number of recent versions to return.

Create a new Deployment

curl -XPOST "$serverUrl/api/deployments"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"deployment":{
    "name": "example",
    "description": "Example deployment"
  }}'

The above command returns JSON structured like this:

{
  "success": true,
  "deployment": {
    "id": 1,
    "name": "example",
    "description": "Example deployment",
    "lastUpdated": "2020-09-10T18:58:55+0000",
    "dateCreated": "2020-09-10T18:58:55+0000",
    "versionCount": 0,
    "versions": []
  }
}

This endpoint will create a new deployment that is ready to have versions added to it.

HTTP Request

POST $serverUrl/api/deployments

Deployment JSON Parameters

Parameter Default Description
name Name, a unique identifier for the deployment
description Description

Update a Deployment

curl -XPUT "$serverUrl/api/deployments/:id"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"deployment":{
    "name": "example",
    "description": "An example deployment"
  }}'

The above command returns JSON structured like this:

{
  "success": true,
  "deployment": {
    "id": 1,
    "name": "example",
    "description": "An example deployment",
    "dateCreated": "2020-09-10T18:58:55+0000",
    "lastUpdated": "2020-09-10T18:62:51+0000",
    "versionCount": 0,
    "versions": []
  }
}

This endpoint will update an existing deployment.

HTTP Request

PUT $serverUrl/api/deployments/:id

Deployment JSON Parameters

Parameter Default Description
name Name, a unique identifier for the deployment
description Description

Delete a Deployment

curl -XDELETE "$serverUrl/api/deployments/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint will delete an existing deployment.

HTTP Request

DELETE $serverUrl/api/deployments/:id

URL Parameters

Parameter Description
id The ID of the deployment

Get All Versions For a Deployment

curl "$serverUrl/api/deployments/:deploymentId/versions" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "versions": [
    {
      "id": 1,
      "deployType": "file",
      "deploymentId": 1,
      "fetchUrl": null,
      "gitUrl": null,
      "gitRef": null,
      "userVersion": "1.0",
      "version": "1.0",
      "status": "created",
      "dateCreated": "2020-10-06T12:56:36+0000",
      "lastUpdated": "2020-10-06T12:56:36+0000"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint returns a paginated list of versions for a specific deployment.

HTTP Request

GET $serverUrl/api/deployments/:deploymentId/versions

URL Parameters

Parameter Description
deploymentId The ID of the deployment

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Filter by wildcard search of version number
version Filter by version number (userVersion)
type Filter by type (deployType), file, git, fetch
dateCreated Filter by dateCreated, the created timestamp is more recent or equal to the date specified
lastUpdated Filter by lastUpdated, the last modified timestamp is more recent or equal to the date specified

Get a Specific Deployment Version

curl "$serverUrl/api/deployments/:deploymentId/versions/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "version": {
    "id": 1,
    "deployType": "file",
    "deploymentId": 1,
    "fetchUrl": null,
    "gitUrl": null,
    "gitRef": null,
    "userVersion": "1.0",
    "version": "1.0",
    "status": "created",
    "dateCreated": "2020-10-06T12:56:36+0000",
    "lastUpdated": "2020-10-06T12:56:36+0000"
  }
}

This endpoint retrieves a specific deployment version.

HTTP Request

GET $serverUrl/api/deployments/:deploymentId/versions/:id

URL Parameters

Parameter Description
deploymentId The ID of the deployment
id The ID of the deployment version

Create a new Deployment Version

curl -XPOST "$serverUrl/api/deployments/:deploymentId/versions"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"version":{
    "version": "1.0",
    "deployType": "git"
  }}'

The above command returns JSON structured like this:

{
  "success": true,
  "version": {
    "id": 1,
    "deployType": "file",
    "deploymentId": 21,
    "fetchUrl": null,
    "gitUrl": null,
    "gitRef": null,
    "userVersion": "1.0",
    "version": "1.0",
    "status": "created",
    "dateCreated": "2020-10-06T13:23:33+0000",
    "lastUpdated": "2020-10-06T13:23:33+0000"
  }
}

This endpoint will create a new deployment version that is ready to have files uploaded to it. The default type is file, which has files directly uploaded via Morpheus. Alternatively, the type git or fetch can be used to just point to a repository or remote url.

HTTP Request

POST $serverUrl/api/deployments/:deploymentId/versions

URL Parameters

Parameter Description
deploymentId The ID of the deployment

Deployment Version JSON Parameters

Parameter Default Description
version Version number (userVersion), a unique version identifier for the deployment version.
userVersion Alias for version
deployType file Deploy Type, eg. file, git, fetch
gitUrl Git URL, git repository url to fetch files from, only applies to type git
gitRef Git Ref, git reference to use, only applies to type git
fetchUrl Fetch URL, location to fetch files from, only applies to type fetch

Update a Deployment Version

curl -XPUT "$serverUrl/api/deployments/:deploymentId/versions/:id"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"deployment":{
    "name": "example",
    "description": "An example deployment"
  }}'

The above command returns JSON structured like this:

{
  "success": true,
  "deployment": {
    "id": 1,
    "name": "example",
    "description": "An example deployment",
    "dateCreated": "2020-09-10T18:58:55+0000",
    "lastUpdated": "2020-09-10T18:62:51+0000",
    "versionCount": 0,
    "versions": []
  }
}

This endpoint will update an existing deployment.

HTTP Request

PUT $serverUrl/api/deployments/:deploymentId/versions/:id

URL Parameters

Parameter Description
deploymentId The ID of the deployment
id The ID of the deployment version

Deployment JSON Parameters

Parameter Default Description
version Version number (userVersion), a unique version identifier for the deployment version.
userVersion Alias for version
deployType file Deploy Type, eg. file, git, fetch
gitUrl Git URL, git repository url to fetch files from, only applies to type git
gitRef Git Ref, git reference to use, only applies to type git
fetchUrl Fetch URL, location to fetch files from, only applies to type fetch

Delete a Deployment Version

curl -XDELETE "$serverUrl/api/deployments/:deploymentId/versions/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint will delete an existing deployment version.

HTTP Request

DELETE $serverUrl/api/deployments/:deploymentId/versions/:id

URL Parameters

Parameter Description
deploymentId The ID of the deployment
id The ID of the deployment version

List Deployment Files

curl "$serverUrl/api/deployments/:deploymentId/versions/:id/files" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "files": [
    {
      "name": "public",
      "directory": true,
      "contentLength": null,
      "contentType": null
    },
    {
      "name": "index.html",
      "directory": false,
      "contentLength": 12927342,
      "contentType": "text/plain"
    },
    {
      "name": "config.ini",
      "directory": false,
      "contentLength": 61932,
      "contentType": "text/plain"
    }
  ]
}

This endpoint returns a of files for a specific deployment version. This only applies to deploy type file. Files are sorted alphabetically, with directories appearing at the beginning of the list.

The filepath parameter can be specified to search for specific files or directories.

HTTP Request

GET $serverUrl/api/deployments/:deploymentId/versions/:id/files/:filepath

URL Parameters

Parameter Description
deploymentId The ID of the deployment
filepath The path to to search for files under. Default is the root directory /.

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Filter by wildcard search of version number
version Filter by version number (userVersion)

Get a Specific Deployment File

curl "$serverUrl/api/deployments/:deploymentId/versions/:id/files/:filepath" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "files": [
    {
      "name": "config.ini",
      "directory": false,
      "contentLength": 61932,
      "contentType": "text/plain"
    }
  ]
}

This is the same endpoint as list deployment files, but it uses the filepath parameter to find a specific file by name. Only files and directories matching the specified filepath or in a specified directory are returned, not the entire file tree.

To list files under a directory, use a trailing / in the filepath parameter. For example /api/deployments/1/versions/1/files/config/environments/.

HTTP Request

GET $serverUrl/api/deployments/:deploymentId/versions/:id/files/:filepath

URL Parameters

Parameter Description
deploymentId The ID of the deployment
filepath The name of the file or directory being fetched

Upload a Deployment File

curl -XPOST "$serverUrl/api/deployments/:deploymentId/versions/:id/files/config.ini"
  -H "Authorization: BEARER $accessToken"
  -F 'file=@filename'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint will upload a file for a specific deployment version. This will overwrite the file if one with the same name exists already.

HTTP Request

POST $serverUrl/api/deployments/:deploymentId/versions/:id/files/:filepath

URL Parameters

Parameter Description
deploymentId The ID of the deployment
id The ID of the deployment version
filepath The name of the file being uploaded

Expects multipart form data as the request format, not JSON.

Delete a Deployment File

curl -XDELETE "$serverUrl/api/deployments/:deploymentId/versions/:id/files/:filepath" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint will delete an existing deployment file. To recursively delete a directory and all of its contents, the force parameter must be specified.

HTTP Request

DELETE $serverUrl/api/deployments/:deploymentId/versions/:id/files/:filepath

URL Parameters

Parameter Description
deploymentId The ID of the deployment
id The ID of the deployment version
filepath The name of the file or directory being deleted

Query Parameters

Parameter Default Description
force false Force delete, use true to recursively delete a directory and all of its contents.

Deploys

Deploys are the execution and installation of deployment versions on your instances. Each deploy represents the installation of a specific version to an instance. This usually involves the installation of one or more files.

Provides API to view the deploy history for instances and also a means to deploy a new version or rollback to a previous version.

A deploy may also be referred to as an instance deployment or appDeploy.

Get all Deploys

curl "$serverUrl/api/deploys" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "appDeploys": [
    {
      "id": 28,
      "instanceId": 347,
      "instance": {
        "id": 347,
        "name": "testsite-2"
      },
      "deployment": {
        "id": 17,
        "name": "testsite",
        "deployType": "file"
      },
      "deploymentVersionId": 58,
      "deploymentVersion": {
        "id": 58,
        "userVersion": "5.0.9",
        "deployType": "file"
      },
      "config": {

      },
      "status": "committed",
      "deployDate": "2020-10-03T00:33:35+0000",
      "dateCreated": "2020-10-03T00:33:30+0000",
      "lastUpdated": "2020-10-03T00:33:35+0000"
    },
    {
      "id": 27,
      "instanceId": 346,
      "instance": {
        "id": 346,
        "name": "testsite-1"
      },
      "deployment": {
        "id": 17,
        "name": "testsite",
        "deployType": "file"
      },
      "deploymentVersionId": 58,
      "deploymentVersion": {
        "id": 58,
        "userVersion": "5.0.9",
        "deployType": "file"
      },
      "config": {

      },
      "status": "committed",
      "deployDate": "2020-10-03T00:33:35+0000",
      "dateCreated": "2020-10-03T00:33:30+0000",
      "lastUpdated": "2020-10-03T00:33:35+0000"
    },
    {
      "id": 26,
      "instanceId": 346,
      "instance": {
        "id": 346,
        "name": "testsite-1"
      },
      "deployment": {
        "id": 17,
        "name": "testsite",
        "deployType": "file"
      },
      "deploymentVersionId": 57,
      "deploymentVersion": {
        "id": 57,
        "userVersion": "5.0.8",
        "deployType": "file"
      },
      "config": {

      },
      "status": "archived",
      "deployDate": "2020-10-03T00:30:44+0000",
      "dateCreated": "2020-10-03T00:30:41+0000",
      "lastUpdated": "2020-10-03T00:33:35+0000"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all deploys.

HTTP Request

GET $serverUrl/api/deploys

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Filter by wildcard search of deployment name, version number, and instance name
name Filter by deployment name
deploymentId Filter by deployment id
instanceName Filter by instance name
instanceId Filter by instance id
version Filter by deployment version number (userVersion)
versionId Filter by deployment version id
createdById Filter by owner (user) id
deployType Filter by deployType: file, git, fetch
dateCreated Filter by dateCreated, the created timestamp is more recent or equal to the date specified
lastUpdated Filter by lastUpdated, the last modified timestamp is more recent or equal to the date specified
deployDate Filter by deployDate, deployment completion timestamp is more recent or equal to the date specified
status Filter by status: staged, deploying, commited, archived

Get all Deploys for an Instance

curl "$serverUrl/api/instances/:instanceId/deploys" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "appDeploys": [
    {
      "id": 27,
      "instanceId": 346,
      "instance": {
        "id": 346,
        "name": "testsite-1"
      },
      "deployment": {
        "id": 17,
        "name": "testsite",
        "deployType": "file"
      },
      "deploymentVersionId": 58,
      "deploymentVersion": {
        "id": 58,
        "userVersion": "5.0.9",
        "deployType": "file"
      },
      "config": {

      },
      "status": "committed",
      "deployDate": "2020-10-03T00:33:35+0000",
      "dateCreated": "2020-10-03T00:33:30+0000",
      "lastUpdated": "2020-10-03T00:33:35+0000"
    },
    {
      "id": 26,
      "instanceId": 346,
      "instance": {
        "id": 346,
        "name": "testsite-1"
      },
      "deployment": {
        "id": 17,
        "name": "testsite",
        "deployType": "file"
      },
      "deploymentVersionId": 57,
      "deploymentVersion": {
        "id": 57,
        "userVersion": "5.0.8",
        "deployType": "file"
      },
      "config": {

      },
      "status": "archived",
      "deployDate": "2020-10-03T00:30:44+0000",
      "dateCreated": "2020-10-03T00:30:41+0000",
      "lastUpdated": "2020-10-03T00:33:35+0000"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all deploys for a specific instance.

HTTP Request

GET $serverUrl/api/instances/:instanceId/deploys

URL Parameters

Parameter Description
instanceId ID of the instance

Query Parameters

Same as get all deploys.

Deploy to an Instance

curl -XPOST "$serverUrl/api/instances/:instanceId/deploys"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"appDeploy":{
    "deploymentId": 17,
    "version": "5.0.9"
  }}'

The above command returns JSON structured like this:

{
  "appDeploy": {
    "id": 27,
    "instanceId": 346,
    "instance": {
      "id": 346,
      "name": "jd-testsite-2"
    },
    "deployment": {
      "id": 17,
      "name": "testsite",
      "deployType": "file"
    },
    "deploymentVersionId": 58,
    "deploymentVersion": {
      "id": 58,
      "userVersion": "5.0.9",
      "version": "5.0.9",
      "deployType": "file"
    },
    "config": {
      "overwrite": true
    },
    "status": "open",
    "deployDate": "2020-10-03T00:33:35+0000",
    "createdBy": {
      "id": 1,
      "username": "admin"
    },
    "dateCreated": "2020-10-03T00:33:30+0000",
    "lastUpdated": "2020-10-03T00:33:35+0000"
  }
}

This endpoint will deploy the specified deployment version to specified instance. The version to deploy can be identified with deploymentId and version or with versionId alone.

By default, the deployment is executed right away. To prevent this so that it can be run manually later on.

HTTP Request

POST $serverUrl/api/instances/:instanceId/deploys

URL Parameters

Parameter Description
instanceId ID of the instance

JSON Parameters

These parameters should be passed under an object called appDeploy.

Parameter Default Description
deploymentId Deployment ID.
version Deployment Version number identifier (userVersion). Can be passed along with deploymentId to identify the version
versionId Deployment Version ID. This can be passed instead of deploymentId and version.
config Map of configuration properties that vary by instance type.
stageOnly false Stage Only, do not run the deploy right away and instead set status to staged so it can be deployed later on.

Update a Deploy

curl -XPUT "$serverUrl/api/deploys/:id"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"appDeploy":{
    "config": { }
  }}'

The above command returns JSON structured like this:

{
  "appDeploy": {
    "id": 27,
    "instanceId": 346,
    "instance": {
      "id": 346,
      "name": "jd-testsite-2"
    },
    "deployment": {
      "id": 17,
      "name": "testsite",
      "deployType": "file"
    },
    "deploymentVersionId": 58,
    "deploymentVersion": {
      "id": 58,
      "userVersion": "5.0.9",
      "version": "5.0.9",
      "deployType": "file"
    },
    "config": {
      "overwrite": true
    },
    "status": "staged",
    "deployDate": "2020-10-03T00:33:35+0000",
    "createdBy": {
      "id": 1,
      "username": "admin"
    },
    "dateCreated": "2020-10-03T00:33:30+0000",
    "lastUpdated": "2020-10-03T00:33:35+0000"
  }
}

This endpoint will update an existing deploy. This is typically only needed to change settings on a deploy that is staged, before it is run.

HTTP Request

PUT $serverUrl/api/deploys/:id

URL Parameters

Parameter Description
id ID of the deploy (appDeploy)

JSON Deploy Parameters

Parameter Default Description
config JSON encoded list of parameters that varies by instance type.

Run a Deploy

curl -XPOST "$serverUrl/api/deploys/:id/deploy"
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"appDeploy":{
    "config": { }
  }}'

The above command returns JSON structured like this:

{
  "appDeploy": {
    "id": 27,
    "instanceId": 346,
    "instance": {
      "id": 346,
      "name": "jd-testsite-2"
    },
    "deployment": {
      "id": 17,
      "name": "testsite",
      "deployType": "file"
    },
    "deploymentVersionId": 58,
    "deploymentVersion": {
      "id": 58,
      "userVersion": "5.0.9",
      "version": "5.0.9",
      "deployType": "file"
    },
    "config": {
      "overwrite": true
    },
    "status": "deploying",
    "deployDate": "2020-10-03T00:33:35+0000",
    "createdBy": {
      "id": 1,
      "username": "admin"
    },
    "dateCreated": "2020-10-03T00:33:30+0000",
    "lastUpdated": "2020-10-03T00:33:35+0000"
  }
}

This endpoint will run an existing instance deploy. This is for running a new staged deploy or to rollback to previous version by re-running a deploy that is archived.

HTTP Request

POST $serverUrl/api/deploys/:id/deploy

URL Parameters

Parameter Description
id ID of the deploy (appDeploy)

JSON Deploy Parameters

Parameter Default Description
config JSON encoded list of parameters that varies by instance type.

Delete a Deploy

curl -XDELETE "$serverUrl/api/deploys/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint will delete an archived instance deploy.

HTTP Request

DELETE $serverUrl/api/deploys/:id

URL Parameters

Parameter Description
id The ID of the deploy (appDeploy)

Infrastructure

The Infrastructure API endpoints provide management of Groups, Clouds, Clusters, Hosts, Networks, Storage, Keys & Certs, etc.

Groups

Groups are used to organize provisioned servers in your infrastructure. When a user on the system provisions an instance like MySQL, they can select which group to provision the instance into. This can be used to scope servers by environment or by region.

A Group may also be referred to as a Site or site.

Get All Groups

curl "$serverUrl/api/groups"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "groups": [
    {
      "id": 1,
      "accountId": 1,
      "name": "Amazon East",
      "code": "amazon",
      "active": true,
      "location": null,
      "zones": [
        {
          "id": 1,
          "accountId": 1,
          "groupId": 1,
          "name": "VPC 1a",
          "description": "1a VPC Subnet",
          "location": null,
          "visibility": "private",
          "zoneTypeId": 1
        }
      ]
    }
  ]
}

This endpoint retrieves all groups and a list of zones associated with the group by id.

HTTP Request

GET $serverUrl/api/groups

Query Parameters

Parameter Default Description
lastUpdated A date filter, restricts query to only load groups updated more recent or equal to the date specified
name If specified will return an exact match group

Get a Specific Group

curl "$serverUrl/api/groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "group": {
    "id": 1,
    "accountId": 1,
    "name": "Vagrant",
    "code": null,
    "active": true,
    "location": null,
    "zones": [
      {
        "id": 1,
        "accountId": 1,
        "groupId": 1,
        "name": "Davids Laptop",
        "description": "My Laptop Vagrant",
        "location": null,
        "visibility": "private",
        "zoneTypeId": 1
      }
    ]
  }
}

This endpoint retrieves a specific group.

HTTP Request

GET $serverUrl/api/groups/:id

URL Parameters

Parameter Description
ID The ID of the group to retrieve

Create a Group

curl -XPOST "$serverUrl/api/groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"group":{
    "name": "My Group",
    "description": "My description",
    "location": "US EAST"
  }}'

The above command returns JSON structured like getting a single group:

HTTP Request

POST $serverUrl/api/groups

JSON Check Group Parameters

Parameter Default Description
name A unique name scoped to your account for the group
code Optional code for use with policies
location Optional location argument for your group

Updating a Group

curl -XPUT "$serverUrl/api/groups/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"group":{
    "name": "My Group",
    "location": "US EAST"
  }}'

The above command returns JSON structured like getting a single group:

HTTP Request

PUT $serverUrl/api/groups/:id

JSON Check Group Parameters

Parameter Default Description
name A unique name scoped to your account for the group
code Optional code for use with policies
location Optional location for your group

Updating Group Zones

curl -XPUT "$serverUrl/api/groups/1/update-zones" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"group":{
    "zones": [
      {"id": 1}, {"id": 2}, {"id": 5}
    ]
  }}'

The above command returns JSON Structured like this:

{
  "success": true
}

This will update the zones that are assigned to the group. Any zones that are not passed in the zones parameter will be removed from the group.

HTTP Request

PUT $serverUrl/api/groups/:id/update-zones

JSON Update Group Zones Parameters

Parameter Default Description
zones An array of all the zones assigned to this group.

Delete a Group

curl -XDELETE "$serverUrl/api/groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

If a group has zones or servers still tied to it, a delete action will fail

HTTP Request

DELETE $serverUrl/api/groups/:id

Clouds

Clouds are a means of zoning various servers based on provisioning type or subnets. Typically an instance or host belongs to a cloud. The cloud holds the credentials necessary to provision virtual machines on the cloud provider’s api. Cloud provider types include: Openstack, Amazon AWS, Nutanix, VMWare vCenter, etc. Of course, we also have the Standard cloud type which allows for manual vm procurement.

A Cloud may also be referred to as a Zone or zone.

Get All Clouds

curl "$serverUrl/api/zones"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "zones": [
    {
      "id": 2,
      "uuid": "141e8db2-22e1-4fec-8c7f-28d8b5abda82",
      "externalId": null,
      "name": "Test Cloud",
      "code": "test",
      "location": null,
      "owner": {
        "id": 1,
        "name": "Morpheus Sandbox"
      },
      "accountId": 1,
      "account": {
        "id": 1,
        "name": "Morpheus Sandbox"
      },
      "visibility": "private",
      "enabled": true,
      "status": "ok",
      "statusMessage": null,
      "zoneType": {
        "id": 1,
        "code": "standard",
        "name": "Morpheus"
      },
      "zoneTypeId": 1,
      "guidanceMode": "off",
      "storageMode": "lvm",
      "agentMode": "cloudInit",
      "userDataLinux": null,
      "userDataWindows": null,
      "consoleKeymap": null,
      "containerMode": "all",
      "serviceVersion": null,
      "costingMode": "off",
      "inventoryLevel": null,
      "timezone": null,
      "apiProxy": null,
      "provisioningProxy": null,
      "networkDomain": null,
      "domainName": "localdomain",
      "regionCode": null,
      "autoRecoverPowerState": false,
      "scalePriority": 1,
      "config": {
        "applianceUrl": "",
        "configManagementId": "",
        "datacenterName": "",
        "provider": "standard",
        "importExisting": "on",
        "networkServer.id": "unmanaged",
        "networkServer": {
          "id": "unmanaged"
        },
        "securityMode": "off",
        "certificateProvider": "internal",
        "backupMode": "internal",
        "replicationMode": "-1",
        "dnsIntegrationId": "",
        "configCmdbId": "",
        "configCmId": "",
        "kubeToken": "************",
        "kubeUrl": "https://10.0.0.59:6443",
        "securityServer": "off",
        "serviceRegistryId": "",
        "enableNetworkTypeSelection": null
      },
      "dateCreated": "2017-03-28T19:36:46Z",
      "lastUpdated": "2021-01-28T17:55:43Z",
      "groups": [
        {
          "id": 2,
          "name": "All Clouds",
          "accountId": 1
        },
        {
          "id": 14,
          "name": "Automation",
          "accountId": 1
        }
      ],
      "securityServer": null,
      "stats": {
        "serverCounts": {
          "all": 0,
          "host": 0,
          "hypervisor": 0,
          "containerHost": 0,
          "vm": 0,
          "baremetal": 0,
          "unmanaged": 0
        }
      },
      "serverCount": 0
    },
    {
      "id": 1,
      "uuid": "9a217c80-c9e0-1459-97b9-1abb33a6c8b2",
      "externalId": "200121726117",
      "name": "AWS Test",
      "code": "awstest",
      "location": "",
      "accountId": 1,
      "account": {
        "id": 1,
        "name": "Morpheus Sandbox"
      },
      "visibility": "private",
      "enabled": true,
      "status": "ok",
      "statusMessage": null,
      "zoneType": {
        "id": 3,
        "code": "amazon",
        "name": "Amazon"
      },
      "zoneTypeId": 3,
      "guidanceMode": "off",
      "storageMode": "standard",
      "agentMode": "cloudInit",
      "userDataLinux": null,
      "userDataWindows": null,
      "consoleKeymap": null,
      "containerMode": "docker",
      "serviceVersion": null,
      "costingMode": "full",
      "inventoryLevel": "full",
      "timezone": null,
      "apiProxy": null,
      "provisioningProxy": null,
      "networkDomain": null,
      "domainName": "localdomain",
      "regionCode": "ec2.us-west-1.amazonaws.com",
      "autoRecoverPowerState": true,
      "scalePriority": 1,
      "config": {
        "endpoint": "ec2.us-west-1.amazonaws.com",
        "accessKey": "my-access-key",
        "secretKey": "************",
        "stsAssumeRole": "",
        "isVpc": "true",
        "vpc": "",
        "imageStoreId": "",
        "ebsEncryption": "off",
        "costingBucket": "myorg.billing",
        "costingRegion": "us-west-1",
        "costingFolder": "reports",
        "costingReport": "cloudability",
        "costingAccessKey": "",
        "costingSecretKey": "",
        "linkedAccountId": "",
        "applianceUrl": "",
        "datacenterName": "",
        "networkServer.id": "1510",
        "networkServer": {
          "id": "1510"
        },
        "certificateProvider": "internal",
        "backupMode": "internal",
        "replicationMode": "-1",
        "dnsIntegrationId": "",
        "serviceRegistryId": "",
        "configManagementId": "",
        "configCmdbId": "",
        "configCmId": "",
        "securityServer": "null"
      },
      "dateCreated": "2020-05-08T03:04:16Z",
      "lastUpdated": "2021-01-28T17:55:54Z",
      "groups": [
        {
          "id": 42367,
          "name": "AWS Test",
          "accountId": 1
        }
      ],
      "securityServer": null,
      "stats": {
        "serverCounts": {
          "all": 0,
          "host": 0,
          "hypervisor": 0,
          "containerHost": 0,
          "vm": 55,
          "baremetal": 0,
          "unmanaged": 55
        }
      },
      "serverCount": 0
    }
  ],
  "meta": {
    "offset": 0,
    "max": "25",
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all zones and a list of zones associated with the zone by id.

HTTP Request

GET $serverUrl/api/zones

Query Parameters

Parameter Default Description
lastUpdated A date filter, restricts query to only load zones updated more recent or equal to the date specified
name If specified will return an exact match zone
type If specified will return all zones by type code (standard,openstack,amazon)
groupId If specified will return all zones assigned to a server group by id.

Get a Specific Cloud

curl "$serverUrl/api/zones/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "zone": {
    "id": 1,
    "uuid": "9a217c80-c9e0-1459-97b9-1abb33a6c8b2",
    "externalId": "200121726117",
    "name": "AWS Test",
    "code": "awstest",
    "location": "",
    "owner": {
        "id": 1,
        "name": "Morpheus Sandbox"
      },
    "accountId": 1,
    "account": {
      "id": 1,
      "name": "Morpheus Sandbox"
    },
    "visibility": "private",
    "enabled": true,
    "status": "ok",
    "statusMessage": null,
    "zoneType": {
      "id": 3,
      "code": "amazon",
      "name": "Amazon"
    },
    "zoneTypeId": 3,
    "guidanceMode": "off",
    "storageMode": "standard",
    "agentMode": "cloudInit",
    "userDataLinux": null,
    "userDataWindows": null,
    "consoleKeymap": null,
    "containerMode": "docker",
    "serviceVersion": null,
    "costingMode": "full",
    "inventoryLevel": "full",
    "timezone": null,
    "apiProxy": null,
    "provisioningProxy": null,
    "networkDomain": null,
    "domainName": "localdomain",
    "regionCode": "ec2.us-west-1.amazonaws.com",
    "autoRecoverPowerState": true,
    "scalePriority": 1,
    "config": {
      "endpoint": "ec2.us-west-1.amazonaws.com",
      "accessKey": "my-access-key",
      "secretKey": "************",
      "stsAssumeRole": "",
      "isVpc": "true",
      "vpc": "",
      "imageStoreId": "",
      "ebsEncryption": "off",
      "costingBucket": "myorg.billing",
      "costingRegion": "us-west-1",
      "costingFolder": "reports",
      "costingReport": "cloudability",
      "costingAccessKey": "",
      "costingSecretKey": "",
      "linkedAccountId": "",
      "applianceUrl": "",
      "datacenterName": "",
      "networkServer.id": "1510",
      "networkServer": {
        "id": "1510"
      },
      "certificateProvider": "internal",
      "backupMode": "internal",
      "replicationMode": "-1",
      "dnsIntegrationId": "",
      "serviceRegistryId": "",
      "configManagementId": "",
      "configCmdbId": "",
      "configCmId": "",
      "securityServer": "null"
    },
    "dateCreated": "2020-05-08T03:04:16Z",
    "lastUpdated": "2021-01-28T17:55:54Z",
    "groups": [
      {
        "id": 42367,
        "name": "AWS Test",
        "accountId": 1
      }
    ],
    "securityServer": null,
    "stats": {
      "serverCounts": {
        "all": 0,
        "host": 0,
        "hypervisor": 0,
        "containerHost": 0,
        "vm": 55,
        "baremetal": 0,
        "unmanaged": 55
      }
    },
    "serverCount": 0
  }
}

This endpoint retrieves a specific zone.

HTTP Request

GET $serverUrl/api/zones/:id

URL Parameters

Parameter Description
ID The ID of the zone to retrieve

Create a Cloud

curl -XPOST "$serverUrl/api/zones" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"zone":{
    "name": "My Cloud",
    "code": "mycloud",
    "description": "My description",
    "location": "US EAST",
    "zoneType": {"code": "standard"},
    "groupId": 1
  }}'

The above command returns JSON structured like getting a single cloud:

HTTP Request

POST $serverUrl/api/zones

JSON Cloud Parameters

Parameter Default Description
name A unique name scoped to your account for the cloud
description Optional description field if you want to put more info there
code Optional code for use with policies
location Optional location for your cloud
visibility private private or public
zoneType “standard” Map containing code or id of the cloud type
groupId Specifies which Server group this cloud should be assigned to
accountId Specifies which Tenant this cloud should be assigned to
enabled true Can be used to disable the cloud
autoRecoverPowerState false Automatically Power on VMs
scalePriority 1 Scale Priority
linkedAccountId Linked Account ID (enter commercial ID to get costing for AWS Govcloud)
config Map containing zone configuration settings. See the section on specific zone types for details.

Additional config properties are dynamic and depend on the specified type of cloud. See Cloud Types.

Updating a Cloud

curl -XPUT "$serverUrl/api/zones/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"zone":{
    "name": "My Cloud",
    "description": "My description",
    "location": "US EAST",
    "zoneType": {"code": "standard"},
    "groupId": 1,
    "config": null
  }}'

The above command returns JSON structured like getting a single zone:

HTTP Request

PUT $serverUrl/api/zones/:id

JSON Cloud Parameters

Parameter Default Description
name A unique name scoped to your account for the zone
description Optional description field if you want to put more info there
code Optional code for use with policies
location Optional location for your zone
visibility private private or public
accountId Specifies which Tenant this zone should be assigned to
enabled true Can be used to disable the cloud
autoRecoverPowerState Automatically Power on VMs
scalePriority Scale Priority
linkedAccountId Linked Account ID (enter commercial ID to get costing for AWS Govcloud)
config Map containing zone configuration settings. See the section on specific zone types for details.

Additional config properties are dynamic and depend on the type of cloud. See Cloud Types.

Refresh a Cloud

curl -XPOST "$serverUrl/api/zones/:id/refresh" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint provides a way to manually refresh a specific cloud. Each cloud type varies when it comes to what refreshing entails, but it involves operations like discovering changes to servers and networks.

HTTP Request

POST $serverUrl/api/zones/:id/refresh

Delete a Cloud

curl -XDELETE "$serverUrl/api/zones/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

If a zone has zones or servers still tied to it, a delete action will fail

HTTP Request

DELETE $serverUrl/api/zones/:id

Get Security Groups

curl -XGET "$serverUrl/api/zones/1/security-groups" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true,
  "firewallEnabled": true,
  "securityGroups": [
    {
      "id": 19,
      "accountId": 1,
      "name": "All Tomcat Access",
      "description": "Allow everyone to access Tomcat"
    }
  ]
}

This returns a list of all of the security groups applied to a zone and whether the firewall is enabled.

HTTP Request

GET $serverUrl/api/zones/:id/security-groups

Set Security Groups

curl -XPOST "$serverUrl/api/zones/1/security-groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "securityGroupIds": [19, 2] }'

The above command returns JSON structure similar to the ‘get’ of security groups.

HTTP Request

POST $serverUrl/api/zones/:id/security-groups

JSON Parameters

Parameter Default Description
securityGroupIds List of all security groups ids which should be applied. If no security groups should apply, pass ’[]’

Cloud Types

Fetch a paginated list of available cloud types. This returns the configuration options for each type.

curl "$serverUrl/api/zone-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "zoneTypes": [
    {
      "id": 3,
      "name": "Amazon",
      "code": "amazon",
      "description": "amazon zone",
      "serverTypes": [],
      "optionTypes": []
    },
    {
      "id": 2,
      "name": "Openstack",
      "code": "openstack",
      "description": "openstac zone",
      "serverTypes": [],
      "optionTypes": []
    },
    {
      "id": 1,
      "name": "Standard",
      "code": "standard",
      "description": "Standard zone - manually managed servers or virtual machines"
      "serverTypes": [],
      "optionTypes": []
    }
  ]
}

HTTP Request

GET $serverUrl/api/zone-types

Query Parameters

Parameter Default Description
max Max number of results to return. Default is all (no limit).
offset 0 Offset of records you want to load
sort displayOrder Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
name Filter by name or code
code Filter by code
phrase Filter by wildcard search of name, code and description
provisionType Filter by Provision Type code

Get Specific Cloud Type

curl "$serverUrl/api/zone-types/1"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "success": true,
  "zoneType": {
    "id": 1,
    "name": "Standard",
    "code": "standard",
    "description": "Standard zone - manually managed servers or virtual machines"
    serverTypes: [],
    optionTypes: []
  }
}

HTTP Request

GET $serverUrl/api/zone-types/:id

Data Stores

Data Stores can be managed for each Compute Zone (Cloud) in your infrastructure.

curl "$serverUrl/api/zones/5/data-stores"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "datastores": [
    {
      "id": 50,
      "name": "datastore1",
      "zone": {
        "id": 34,
        "name": "test-vmware"
      },
      "type": "generic",
      "freeSpace": 421317836800,
      "online": false,
      "active": false,
      "visibility": "private",
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ]
    }
  ],
  "meta": {
    "size": 7,
    "total": 7,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all data stores under a cloud.

HTTP Request

GET $serverUrl/api/zones/:zoneId/data-stores

URL Parameters

Parameter Description
zoneId The ID of the cloud

Query Parameters

Parameter Default Description
phrase Filter on partial match of name
name Filter on exact match of name

Get a Specific Data Store

curl "$serverUrl/api/zones/5/data-stores/50" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "datastore": {
    "id": 50,
    "name": "datastore1",
    "zone": {
      "id": 34,
      "name": "test-vmware"
    },
    "type": "generic",
    "freeSpace": 421317836800,
    "online": true,
    "active": true,
    "visibility": "private",
    "tenants": [
      {
        "id": 1,
        "name": "root"
      }
    ],
    "resourcePermission": {
      "all": false,
      "sites": [
        {
          "id": 1,
          "name": "group1"
        },
        {
          "id": 2,
          "name": "group2"
        },
      ]
    }
  }
}

This endpoint retrieves a specific data store.

HTTP Request

GET $serverUrl/api/zones/:zoneId/data-stores/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the data store to retrieve

Updating a Data Store

curl -XPUT "$serverUrl/api/zones/5/data-stores/50" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"datastore":{
    "active": true,
    "visibility": "private",
    "tenantPermissions": {
      "accounts": [1,2,3,4,5]
    },
    "resourcePermissions": {
      "all": false,
      "sites": [
        {"id": 1}, {"id": 2}, {"id": 3}
      ]
    }
  }}'

The above command returns JSON structured like getting a single data store:

This endpoint allows updating settings for a data store.

HTTP Request

PUT $serverUrl/api/zones/:zoneId/data-stores/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the data store

JSON Parameters

Parameter Default Description
active Activate (true) or disable (false) the datastore
visibility private private or public
tenantPermissions.accounts Array of tenant account ids that are allowed access
tenantPermissions.defaultTarget Array of tenant account ids which should use the data store as the Default
tenantPermissions.defaultStore Array of tenant account ids which should use the data store as the Image Target
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

Resource Pools

Resource Pools can be managed for each Compute Zone (Cloud) in your infrastructure.

curl "$serverUrl/api/zones/5/resource-pools"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "resourcePools": [
    {
      "id": 89,
      "name": "labs",
      "description": "labs - vpc-231b2e3c - 10.50.0.0/16",
      "zone": {
        "id": 8,
        "name": "labs-aws"
      },
      "parent": null,
      "type": "vpc",
      "externalId": "vpc-231b2e3c",
      "iacId": null,
      "visibility": "private",
      "readOnly": false,
      "defaultPool": false,
      "active": true,
      "status": "available",
      "config": {
        "cidrBlock": "10.50.0.0/16",
        "tenancy": "default"
      },
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ],
      "resourcePermission": {
        "all": true,
        "sites": [

        ],
        "allPlans": true,
        "plans": [

        ]
      },
      "depth": 0
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all resource pools under a cloud.

HTTP Request

GET $serverUrl/api/zones/:zoneId/resource-pools

URL Parameters

Parameter Description
zoneId The ID of the cloud

Query Parameters

Parameter Default Description
phrase Filter on partial match of name
name Filter on exact match of name

Get a Specific Resource Pool

curl "$serverUrl/api/zones/5/resource-pools/50" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "resourcePool": {
    "id": 89,
    "name": "labs",
    "description": "labs - vpc-231b2e3c - 10.50.0.0/16",
    "zone": {
      "id": 8,
      "name": "labs-aws"
    },
    "parent": null,
    "type": "vpc",
    "externalId": "vpc-231b2e3c",
    "iacId": null,
    "visibility": "private",
    "readOnly": false,
    "defaultPool": false,
    "active": true,
    "status": "available",
    "config": {
      "cidrBlock": "10.50.0.0/16",
      "tenancy": "default"
    },
    "tenants": [
      {
        "id": 1,
        "name": "root"
      }
    ],
    "resourcePermission": {
      "all": true,
      "sites": [

      ],
      "allPlans": true,
      "plans": [

      ]
    },
    "depth": 0
  }
}

This endpoint retrieves a specific resource pool.

HTTP Request

GET $serverUrl/api/zones/:zoneId/resource-pools/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the resource pool to retrieve

Create a Resource Pool

curl -XPOST "$serverUrl/api/zones/5/resource-pools" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"resourcePool": {
    "name": "mypool",
    "config": {
      "cidrBlock": "10.20.254.0/28",
      "tenancy": "default"
    },
    "tenantPermissions": {
      "accounts": [1,2,3,4,5]
    },
    "resourcePermissions": {
      "all": false,
      "sites": [
        {"id": 1}, {"id": 2}, {"id": 3}
      ]
    }
  }}'

The above command returns JSON structured like getting a single resource pool:

This endpoint allows updating settings for a resource pool. Only certain types of clouds support creating and deleting resource pools. Configuration options vary by type.

HTTP Request

POST $serverUrl/api/zones/:zoneId/resource-pools

URL Parameters

Parameter Description
zoneId The ID of the cloud

JSON Parameters

Parameter Default Description
name Name
defaultPool false Set as the Default Pool
defaultImage false Set as the Default Image Target
active true Activate (true) or disable (false) the resource pool
visibility private private or public
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all true Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access
resourcePermissions.allPlans true Pass true to allow access all plans
resourcePermissions.plans Array of plans that are allowed access

JSON Parameters for Amazon Resource Pool

Parameter Default Description
config.cidrBlock Provide the base CIDR Block to use for this VPC (must be between a /16 and /28 Block)
config.tenancy default default or dedicated

JSON Parameters for Cloud Foundry

Parameter Default Description
config.managers [] Array of manager usernames
config.developers [] Array of developer usernames
config.auditors [] Array of auditor usernames

Updating a Resource Pool

curl -XPUT "$serverUrl/api/zones/5/resource-pools/50" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"resourcePool":{
    "active": true,
    "visibility": "private",
    "tenantPermissions": {
      "accounts": [1,2,3,4,5]
    },
    "resourcePermissions": {
      "all": false,
      "sites": [
        {"id": 1}, {"id": 2}, {"id": 3}
      ]
    }
  }}'

The above command returns JSON structured like getting a single resource pool:

This endpoint allows updating settings for a resource pool.

HTTP Request

PUT $serverUrl/api/zones/:zoneId/resource-pools/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the resource pool

JSON Parameters

Parameter Default Description
active Activate (true) or disable (false) the resource pool
visibility private private or public
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access
resourcePermissions.allPlans Pass true to allow access all plans
resourcePermissions.plans Array of plans that are allowed access

Delete a Resource Pool

curl -XDELETE "$serverUrl/api/zones/5/resource-pools/50" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/zones/:zoneId/resource-pools/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the resource pool

Resource Folders

Resource Folders can be managed for each Compute Zone (Cloud) in your infrastructure.

curl "$serverUrl/api/zones/5/folders"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "folders": [
    {
      "id": 50,
      "name": "My Folder",
      "zone": {
        "id": 5,
        "name": "test-vmware"
      },
      "parent": null,
      "type": "default",
      "externalId": "group-v2342",
      "visibility": "private",
      "readOnly": false,
      "defaultFolder": false,
      "defaultStore": false,
      "active": true,
      "tenants": [
        {
          "id": 1,
          "name": "root",
          "defaultStore": false,
          "defaultTarget": false
        }
      ],
      "resourcePermission": {
        "all": true,
        "sites": [

        ],
        "allPlans": true,
        "plans": [

        ]
      },
      "depth": 0
    }
  ],
  "meta": {
    "size": 1,
    "total": 30,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all resource folders under a cloud.

HTTP Request

GET $serverUrl/api/zones/:zoneId/folders

URL Parameters

Parameter Description
zoneId The ID of the cloud

Query Parameters

Parameter Default Description
phrase Filter on partial match of name
name Filter on exact match of name

Get a Specific Resource Folder

curl "$serverUrl/api/zones/5/folders/50" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "folder": {
    "id": 50,
    "name": "My Folder",
    "zone": {
      "id": 5,
      "name": "test-vmware"
    },
    "parent": null,
    "type": "default",
    "externalId": "group-v2342",
    "visibility": "private",
    "readOnly": false,
    "defaultFolder": false,
    "defaultStore": false,
    "active": true,
    "tenants": [
      {
        "id": 1,
        "name": "root",
        "defaultStore": false,
        "defaultTarget": false
      }
    ],
    "resourcePermission": {
      "all": true,
      "sites": [

      ],
      "allPlans": true,
      "plans": [

      ]
    }
  }
}

This endpoint retrieves a specific resource folder.

HTTP Request

GET $serverUrl/api/zones/:zoneId/folders/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the resource folder to retrieve

Updating a Resource Folder

curl -XPUT "$serverUrl/api/zones/5/folders/50" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"folder":{
    "active": true,
    "visibility": "private",
    "tenantPermissions": {
      "accounts": [1]
    },
    "resourcePermissions": {
      "all": false,
      "sites": [
        {"id": 1}, {"id": 2}, {"id": 3}
      ]
    }
  }}'

The above command returns JSON structured like getting a single resource folder:

This endpoint allows updating settings for a resource folder.

HTTP Request

PUT $serverUrl/api/zones/:zoneId/folders/:id

URL Parameters

Parameter Description
zoneId The ID of the cloud
id The ID of the resource folder

JSON Parameters

Parameter Default Description
defaultFolder false Set as the Default Folder
defaultImage false Set as the Default Image Target
active Activate (true) or disable (false) the resource folder
visibility private private or public
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access
resourcePermissions.allPlans Pass true to allow access all plans
resourcePermissions.plans Array of plans that are allowed access

Clusters

Clusters is for creating and managing Kubernetes Clusters, Morpheus managed Docker Clusters, KVM Clusters, or Cloud specific Kubernetes services such as EKS. The Triforce Cluster is a combination Kubernetes, KVM and Functions* Cluster, with all nodes supporting all three provision types.

A Cluster may also be referred to as an Server Group or serverGroup.

Get All Clusters

curl "$serverUrl/api/clusters" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "clusters": [
        {
            "id": 1,
            "name": "cluster-1",
            "code": null,
            "category": null,
            "visibility": "public",
            "description": null,
            "location": null,
            "enabled": false,
            "serviceUrl": null,
            "serviceHost": null,
            "servicePath": null,
            "serviceHostname": null,
            "servicePort": 22,
            "serviceUsername": null,
            "servicePassword": null,
            "serviceToken": null,
            "serviceAccess": null,
            "serviceCert": null,
            "serviceConfig": null,
            "serviceVersion": null,
            "searchDomains": null,
            "enableInternalDns": false,
            "internalId": null,
            "externalId": null,
            "datacenterId": null,
            "status": "provisioning",
            "statusDate": "2019-08-14T04:42:22+0000",
            "statusMessage": null,
            "inventoryLevel": "full",
            "lastSync": "2019-08-09T23:32:04+0000",
            "nextRunDate": "2019-08-14T04:47:22+0000",
            "lastSyncDuration": 138,
            "dateCreated": "2019-07-29T20:34:27+0000",
            "lastUpdated": "2019-08-14T04:42:22+0000",
            "serviceEntry": null,
            "createdBy": {
                "id": 1,
                "username": "root"
            },
            "userGroup": null,
            "layout": {
                "id": 3,
                "name": "Amazon Docker Host",
                "provisionTypeCode": "amazon"
            },
            "owner": {
                "id": 1,
                "name": "Stubby Toes Inc."
            },
            "servers": [
                {
                    "id": 1,
                    "name": "cluster-1",
                    "typeSet": {
                        "id": 5,
                        "code": "kubernetes-amazon-ubuntu-16.04-set",
                        "name": "kubernetes master"
                    },
                    "computeServerType": {
                        "id": 99,
                        "code": "amazonLinux",
                        "nodeType": "morpheus-node"
                    }
                }
            ],
            "accounts": [

            ],
            "integrations": [

            ],
            "site": {
                "id": 2,
                "name": "stubby toes aws group"
            },
            "type": {
                "id": 2,
                "name": "Docker Cluster"
            },
            "zone": {
                "id": 3,
                "name": "stubby toes aws cloud",
                "zoneType": {
                    "id": 12
                }
            },
            "config": null,
            "workers": [
                {
                    "id": 7,
                    "name": "cluster-1",
                    "status": "provisioning",
                    "powerState": "on"
                }
            ],
            "workerCount": 1,
            "workerStats": {
                "usedStorage": 0,
                "maxStorage": 21474836480,
                "usedMemory": 0,
                "maxMemory": 536870912,
                "usedCpu": 0.0,
                "cpuUsage": 0.0,
                "cpuUsagePeak": 0.0,
                "cpuUsageAvg": 0.0
            }
        }
    ],
    "meta": {
        "size": 5,
        "total": 5,
        "max": 25,
        "offset": 0
    }
}

This endpoint retrieves all clusters and a list of clusters associated with the zone by id.

HTTP Request

GET $serverUrl/api/clusters

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name or serviceUrl filter, restricts query to only load clusters which contain the phrase specified
name Name filter, restricts query to only load clusters matching the name specified
zoneId Zone filter, restricts query to only load clusters of a specified zone
typeId Type filter, restricts query to only load clusters of a specified cluster type

Get a Specific Cluster

curl "$serverUrl/api/clusters/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "cluster": {
        "id": 3,
        "name": "kubernetes-cluster",
        "code": null,
        "category": null,
        "visibility": "public",
        "description": null,
        "location": null,
        "enabled": false,
        "serviceUrl": null,
        "serviceHost": null,
        "servicePath": null,
        "serviceHostname": null,
        "servicePort": 22,
        "serviceUsername": null,
        "servicePassword": null,
        "serviceToken": null,
        "serviceAccess": null,
        "serviceCert": null,
        "serviceConfig": null,
        "serviceVersion": null,
        "searchDomains": null,
        "enableInternalDns": false,
        "apiKey": "xxxxx",
        "internalId": null,
        "externalId": null,
        "datacenterId": null,
        "status": "provisioning",
        "statusDate": "2019-07-29T23:44:34+0000",
        "statusMessage": null,
        "inventoryLevel": "full",
        "lastSync": null,
        "nextRunDate": "2019-08-14T04:47:22+0000",
        "lastSyncDuration": null,
        "dateCreated": "2019-07-29T23:40:56+0000",
        "lastUpdated": "2019-08-14T04:43:54+0000",
        "serviceEntry": null,
        "createdBy": {
            "id": 1,
            "username": "root"
        },
        "userGroup": null,
        "layout": {
            "id": 4,
            "name": "Kubernetes 1.14 Cluster on Ubuntu 16.04, Weave, OpenEBS",
            "provisionTypeCode": "amazon"
        },
        "owner": {
            "id": 1,
            "name": "Stubby Toes Inc."
        },
        "servers": [
            {
                "id": 14,
                "name": "kube1-worker-2",
                "computeServerType": {
                    "id": 192,
                    "code": "amazonKubeWorker",
                    "nodeType": "kube-worker"
                }
            },
            {
                "id": 12,
                "name": "kube1-master",
                "computeServerType": {
                    "id": 191,
                    "code": "amazonKubeMaster",
                    "nodeType": "kube-master"
                }
            },
            {
                "id": 13,
                "name": "kube1-worker-1",
                "computeServerType": {
                    "id": 192,
                    "code": "amazonKubeWorker",
                    "nodeType": "kube-worker"
                }
            },
            {
                "id": 15,
                "name": "kube1-worker-3",
                "computeServerType": {
                    "id": 192,
                    "code": "amazonKubeWorker",
                    "nodeType": "kube-worker"
                }
            }
        ],
        "accounts": [

        ],
        "integrations": [

        ],
        "site": {
            "id": 2,
            "name": "aws group"
        },
        "type": {
            "id": 1,
            "name": "Kubernetes Cluster"
        },
        "zone": {
            "id": 3,
            "name": "aws cloud",
            "zoneType": {
                "id": 12
            }
        },
        "config": "{\"initConfig\":\"\"}",
        "workerStats": {
            "usedStorage": 0,
            "maxStorage": 53687091200,
            "usedMemory": 0,
            "maxMemory": 2147483648,
            "usedCpu": 0.0,
            "cpuUsage": 0.0,
            "cpuUsagePeak": 0.0,
            "cpuUsageAvg": 0.0
        },
        "containersCount": 35,
        "servicesCount": 1,
        "deploymentsCount": 1,
        "podsCount": 33,
        "jobsCount": 1,
        "volumesCount": 2,
        "namespacesCount": 1,
        "workersCount": 4,
        "permissions": {
            "resourcePool": {
                "id": 12,
                "visibility": "public"
            },
            "resourcePermissions": {
                "allGroups": true,
                "defaultStore": false,
                "allPlans": false,
                "defaultTarget": false,
                "morpheusResourceType": "ComputeZonePool",
                "morpheusResourceId": 12,
                "canManage": false,
                "all": true,
                "account": {
                    "id": 1
                },
                "sites": [
                    {
                        "id": 2,
                        "name": "dans aws group",
                        "default": true
                    }
                ],
                "plans": [
                    {
                        "id": 88,
                        "name": "128MB Memory, 1GB Storage",
                        "default": false
                    }
                ]
            }
        }
    }
}

This endpoint retrieves a specific cluster.

HTTP Request

GET $serverUrl/api/clusters/:id

URL Parameters

Parameter Description
ID ID of the cluster

Create a Cluster

curl -XPOST "$serverUrl/api/clusters" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"cluster": {
        "type": "docker-cluster",
        "name": "stubby toes docker cluster",
        "description": "cluster description",
        "group": {"id": 2},
        "cloud": {"id": 3},
        "layout": "docker-amazon-ubuntu-16.04-single",
        "server": {
            "config": {
                "resourcePool": "vpc-d673ebb3",
                "publicIpType": "subnet",
                "createUser": false
            },
            "name": "tippytoes",
            "plan": {
                "code": "amazon-t2.nano",
                "options": {
                    "maxMemory": 536870912,
                    "cpuCount": 1,
                    "coreCount": 1,
                    "coresPerSocket": 1
                }
            },
            "volumes": [
                {
                    "id": -1,
                    "rootVolume": true,
                    "name": "root",
                    "size": 10,
                    "sizeId": null,
                    "storageType": 10,
                    "datastoreId": null
                }
            ],
            "networkInterfaces": [
                {
                    "network": {
                        "id": "network-20"
                    }
                }
            ],
            "securityGroups": [
                "sg-052d3dacc2b663fdd"
            ],
            "visibility": "private",
            "userGroup": {
                "id": 1
            },
            "networkDomain": null,
            "hostname": null,
            "nodeCount": 3
        }
    }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

POST $serverUrl/api/clusters

JSON Parameters

Parameter Required Default Description
type Y n/a Type of cluster to be created
name Y n/a Name of the cluster to be created
description N Description of the cluster to be created
group.id Y n/a The Group ID to provision the cluster into
cloud.id Y n/a The Cloud ID to provision the host into
layout.id Y n/a The Layout ID for the host type(s) that will be provisioned for the cluster
server Y n/a Key for server configuration, see Server

Server

The server parameter is for server host configuration that are specific to each Provision Type. The Provision Types api can be used to see which options are available.

Parameter Required Default Description
config Y Key for specific host type configuration, see Config
name Y n/a Name to be used for host(s) created in the cluster
plan.id Y The id for the memory and storage option pre-configured within Morpheus.
plan.options N Map of custom options depending on selected service plan . An example would be maxMemory, or maxCores.
volumes N Key for volume configuration, see Volumes
networkInterfaces N Key for network configuration, see Network Interfaces
securityGroups N Key for security group configuration. It should be passed as an array of objects containing the id of the security group to assign the host to
visibility N private Visibility for server host
userGroup.id N User Group ID for server host
hostname N Hostname for server host
nodeCount N Number of workers or hosts

Volumes

The (optional) volumes parameter is for LV configuration, can create additional LVs at provision It should be passed as an array of Objects with the following attributes:

Parameter Required Default Description
id N -1 The id for the LV configuration being created
rootVolume N true If set to false then a non-root LV will be created
name Y root Name/type of the LV being created
size N [from service plan] Size of the LV to be created in GBs
sizeId N Can be used to select pre-existing LV choices from Morpheus
storageType N Identifier for LV type
datastoreId Y The ID of the specific datastore. Auto selection can be specified as auto or autoCluster (for clusters).

Network Interfaces

The networkInterfaces parameter is for network configuration.

The Options API /api/options/zoneNetworkOptions?zoneId=5&provisionTypeId=10 can be used to see which options are available.

It should be passed as an array of Objects with the following attributes:

Parameter Required Default Description
network.id Y n/a id of the network to be used. A network group can be specified instead by prefixing its ID with networkGroup-.
networkInterfaceTypeId Y n/a The id of type of the network interface.
ipAddress Y n/a The ip address. Not applicable when using DHCP or IP Pools.

Config

The config parameter is for configuration options that are specific to each Provision Type. The Provision Types api can be used to see which options are available.

Update Cluster

curl -XPUT "$serverUrl/api/clusters/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"cluster": {
       "name": "Cluster Name",
       "description": "Cluster Description",
       "enabled": true,
       "serviceUrl": "https://api-endpoint.com",
       "refresh": true
      }}' 

The above command returns a similar JSON structure when submitting a GET request for a single cluster

HTTP Request

PUT $serverUrl/api/clusters/:id

URL Parameters

Parameter Description
id The ID of the cluster

JSON Cluster Parameters

Parameter Default Description
name Cluster name
description Cluster description
enabled Cluster enabled
serviceUrl Cluster API Url
refresh Queue cluster refresh

Update Cluster Permissions

curl -XPUT "$serverUrl/api/clusters/1/permissions" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"permissions": {
       "resourcePermissions": {
         "all": true,
         "sites": [{"id": 1, "default": true}],
         "allPlans": true,
         "plans": [{"id": 1, "default": false}]
       }
      }}' 

The above command returns a similar JSON structure when submitting a GET request for a single cluster

HTTP Request

PUT $serverUrl/api/clusters/:id/permissions

URL Parameters

Parameter Description
id The ID of the cluster

JSON Cluster Parameters

Parameter Required Default Description
permissions Y n/a Key for server configuration, see Permissions

Permissions

The permissions parameter is for permissions for clusters and namespaces.

Parameter Default Description
resourcePool.visibility Applicable to clusters only
resourcePermissions.all Pass true to allow access to all groups
resourcePermissions.sites Array of groups that are allowed access
resourcePermissions.allPlans Pass true to allow access to all plans
resourcePermissions.plans Array of plans that are allowed access
tenantPermissions.accounts Array of tenant account ids that are allowed access

Delete a Cluster

curl -XDELETE "$serverUrl/api/clusters/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a cluster and associated resources, hosts, volumes asynchronously

HTTP Request

DELETE $serverUrl/api/clusters/:id

Query Parameters

Parameter Default Description
removeResources on Remove Infrastructure.
removeInstances off Remove Associated Hosts
preserveVolumes off Preserve Volumes
releaseEIPs on Release EIPs
force off Force Delete

Get API Config

curl "$serverUrl/api/clusters/1/api-config" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" 

The above comand returns JSON structure like this:

{
  "serviceUrl": null,
  "serviceHost": null,
  "servicePath": null,
  "serviceHostname": null,
  "servicePort": 22,
  "serviceUsername": null,
  "servicePassword": null,
  "serviceToken": null,
  "serviceAccess": null,
  "serviceCert": null,
  "serviceConfig": null,
  "serviceVersion": null
}

This endpoint retrieves the API configuration for a specified cluster. The configuration is cluster type specific, see API Config Mappings

API Config Mappings

See below for cluster type specific mappings

Kubernetes

Config Purpose
serviceToken API Token
serviceAccess Kube Config

HTTP Request

GET $serverUrl/api/clusters/:id/api-config

URL Parameters

Parameter Description
id The ID of the cluster

List Namespaces (Kubernetes)

curl "$serverUrl/api/clusters/:cluster_id/namespaces" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "namespaces": [
    {
      "id": 1,
      "name": "Namespace",
      "description": "Some details about namespace",
      "regionCode": null,
      "externalId": null,
      "status": "available",
      "active": true
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

HTTP Request

GET $serverUrl/api/clusters/:clusterId/namespaces

URL Parameters

Parameter Description
clusterId The ID of the cluster

Get Namespace (Kubernetes)

curl "$serverUrl/api/clusters/:clusterId/namespaces/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "namespace": {
    "id": 13,
    "visibility": "public",
    "name": "My Namespace",
    "description": "new description",
    "status": "available",
    "active": true,
    "permissions": {
      "resourcePermissions": {
        "allGroups": true,
        "defaultStore": false,
        "allPlans": true,
        "defaultTarget": false,
        "morpheusResourceType": "ComputeZonePool",
        "morpheusResourceId": 13,
        "canManage": false,
        "all": true,
        "account": {
          "id": 1
        },
        "sites": [
          {
            "id": 2,
            "name": "aws group",
            "default": false
          }
        ],
        "plans": [
          {
            "id": 88,
            "name": "128MB Memory, 1GB Storage",
            "default": true
          }
        ]
      }
    }
  }
}

This endpoint retrieves a specific namespace of a cluster

HTTP Request

GET $serverUrl/api/clusters/:clusterId/namespaces/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the namespace

Add Namespace (Kubernetes)

curl -XPOST "$serverUrl/api/clusters/1/namespaces" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"namespace": {
       "name": "Namespace Name",
       "description": "Description",
       "active": true,
       "resourcePermissions": {
         "all": true,
         "allPlans": true,
         "sites": [{"id": 2,"default": true}],
         "plans": [{"id": 88,"default": false}]
       }
      }}'

The above command returns JSON structure like this:

{
  "success": true,
  "namespace": {
    "id": 1,
    "name": "Namespace Name",
    "description": "Description",
    "regionCode": null,
    "externalId": null,
    "status": "available"
  }
}

HTTP Request

POST $serverUrl/api/clusters/:id/namespaces

URL Parameters

Parameter Description
id The ID of the cluster

JSON Cluster Parameters

Parameter Required Default Description
name Y Namespace name
description N Namespace description
active N false Namespace active
resourcePermissions N Key for resource permission configuration, see Resource Permissions

Resource Permissions

The resourcePermissions parameter is a map for namespace group and service plan permissions.

Parameter Required Default Description
all N Pass true to allow access to all groups
sites N Array of groups that are allowed access
allPlans N Pass true to allow access to all service plans
plans N n/a Array of service plans that are allowed access

Update Namespace (Kubernetes)

curl -XPUT "$serverUrl/api/clusters/1/namespaces/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"namespace": {
       "description": "Description",
       "active": true,
       "permissions": {
         "resourcePermissions": {
           "all": true,
           "sites": [{"id": 1, "default": true}],
           "allPlans": true,
           "plans": [{"id": 1, "default": false}]
         }
       }  
      }}'

The above command returns same JSON structure as Add Namespace

HTTP Request

PUT $serverUrl/api/clusters/:clusterId/namespaces/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the namespace

JSON Cluster Parameters

Parameter Required Default Description
description N Namespace description
active N false Namespace active
permissions N Key for resource permission configuration, see Permissions

Delete a Namespace (Kubernetes)

curl -XDELETE "$serverUrl/api/clusters/1/namespaces/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a namespace from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/namespaces/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the namespace to delete

Query Parameters

Parameter Default Description
force off Force Delete

Add Worker

curl -XPOST "$serverUrl/api/clusters/:id/servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"server": {
        "config": {
            "resourcePool": "vpc-d673ebb3",
            "publicIpType": "subnet",
            "createUser": false
        },
        "name": "tippytoes",
        "plan": {
            "code": "amazon-t2.nano",
            "options": {
                "maxMemory": 536870912,
                "cpuCount": 1,
                "coreCount": 1,
                "coresPerSocket": 1
            }
        },
        "volumes": [
            {
                "id": -1,
                "rootVolume": true,
                "name": "root",
                "size": 10,
                "sizeId": null,
                "storageType": 10,
                "datastoreId": null
            }
        ],
        "networkInterfaces": [
            {
                "network": {
                    "id": "network-20"
                }
            }
        ],
        "securityGroups": [
            "sg-052d3dacc2b663fdd"
        ],
        "visibility": "private",
        "userGroup": {
            "id": 1
        },
        "networkDomain": null,
        "hostname": null,
        "nodeCount": 1, 
        "taskSet": {
          "id": 2
        }       
    }}'

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/clusters/:id/servers

URL Parameters

Parameter Description
id The ID of the cluster

JSON Parameters

Parameter Description
server Key for server configuration, see Server

Get Workers

curl "$serverUrl/api/clusters/:id/workers" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "workers": [
    {
      "id": 11,
      "externalId": "i-03a65f2d1d34f4d76",
      "internalId": null,
      "accountId": 1,
      "account": {
        "name": "Stubby Toes Inc."
      },
      "name": "kube-worker-1",
      "visibility": "public",
      "description": null,
      "zoneId": 3,
      "siteId": 2,
      "sshHost": null,
      "sshPort": 22,
      "externalIp": null,
      "internalIp": "172.31.7.195",
      "volumeId": null,
      "platform": null,
      "platformVersion": null,
      "sshUsername": "root",
      "sshPassword": "****",
      "osDevice": "/dev/sda",
      "dataDevice": "/dev/sdb",
      "lvmEnabled": false,
      "apiKey": "xxxxx",
      "softwareRaid": false,
      "dateCreated": "2019-07-29T23:41:19+0000",
      "lastUpdated": "2019-08-09T21:25:44+0000",
      "stats": {
        "usedStorage": null,
        "reservedStorage": 0,
        "maxStorage": 10737418240,
        "usedMemory": 0,
        "reservedMemory": 0,
        "maxMemory": 536870912
      },
      "status": "failed",
      "statusMessage": null,
      "errorMessage": null,
      "statusDate": null,
      "statusPercent": null,
      "statusEta": null,
      "powerState": "unknown",
      "computeServerType": {
        "id": 192,
        "code": "amazonKubeWorker",
        "name": "Amazon Kubernetes Worker",
        "managed": true,
        "externalDelete": true
      },
      "agentInstalled": false,
      "lastAgentUpdate": null,
      "agentVersion": null,
      "maxCores": 1,
      "maxMemory": 536870912,
      "maxStorage": 10737418240,
      "maxCpu": null,
      "serverOs": null,
      "enabled": true,
      "zone": {
        "id": 3,
        "name": "stubby toes aws cloud"
      },
      "plan": {
        "id": 1,
        "code": "amazon-t2.nano",
        "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
      },
      "containers": [

      ]
    }
  ]  
}

This endpoint retrieves workers of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/workers

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
phrase Name filter, restricts query to only load workers matching the name or display name

Get Masters (Kubernetes)

curl "$serverUrl/api/clusters/:id/masters" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured similar to Get Workers

This endpoint retrieves masters of a specified kubernetes cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/masters

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
phrase Name filter, restricts query to only load workers matching the name or display name

Get Volumes

curl "$serverUrl/api/clusters/:id/volumes" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "volumes": [
    {
      "id": 123,
      "displayOrder": 0,
      "active": true,
      "usedStorage": 0,
      "resizeable": true,
      "online": true,
      "deviceDisplayName": "xvda",
      "name": "root",
      "externalId": "vol-076adc80392a1217a",
      "volumeType": "disk",
      "deviceName": "/dev/sda1",
      "removable": false,
      "readOnly": false,
      "zoneId": 3,
      "rootVolume": true,
      "category": "kubernetes.persistentVolumeClaim.cluster.3",
      "status": "provisioned",
      "maxStorage": 21474836480,
      "account": {
        "id": 1
      },
      "type": {
        "id": 10
      }
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves volumes of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/volumes

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load volumes which contain the phrase specified

Delete a Volume

curl -XDELETE "$serverUrl/api/clusters/:clusterId/volumes/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a volume from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/volumes/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the volume to delete

Query Parameters

Parameter Default Description
force off Force Delete

Get Containers

curl "$serverUrl/api/clusters/:id/containers" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "containers": [
    {
      "id": 14,
      "uuid": "",
      "accountId": 1,
      "instance": null,
      "containerType": {
        "id": 50,
        "code": "ubuntu-14.04.03",
        "category": null,
        "name": "Ubuntu 14.04"
      },
      "containerTypeSet": {
        "id": null,
        "code": null,
        "category": null
      },
      "server": {
        "id": 20,
        "name": "cluster 2"
      },
      "cloud": {
        "id": 3,
        "name": "aws cloud"
      },
      "name": "ubuntu_14",
      "ip": "172.31.0.197",
      "internalIp": "172.31.0.197",
      "internalHostname": "container14",
      "externalHostname": "container14",
      "externalDomain": "localdomain",
      "externalFqdn": "container14.localdomain",
      "ports": [

      ],
      "plan": {
        "id": null,
        "code": null,
        "name": null
      },
      "dateCreated": null,
      "lastUpdated": "2019-10-01T13:55:23+0000",
      "statsEnabled": false,
      "status": "unknown",
      "userStatus": "stopped",
      "environmentPrefix": null,
      "stats": {
      },
      "runtimeInfo": {
      },
      "containerVersion": null,
      "repositoryImage": null,
      "planCategory": null,
      "hostname": null,
      "domainName": null,
      "volumeCreated": false,
      "containerCreated": false,
      "maxStorage": null,
      "maxMemory": null,
      "maxCores": null,
      "maxCpu": null,
      "availableActions": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves containers of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/containers

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load containers which contain the phrase specified
resourceLevel Resource level filter: app, system, storage, logging

Get Deployments

curl "$serverUrl/api/clusters/:id/deployments" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "deployments": [
    {
      "id": 4,
      "name": "test deployment display name",
      "code": "test_deployment_code",
      "description": null,
      "category": "kubernetes.deployment.cluster.3",
      "resourceLevel": "app",
      "resourceType": "deployment",
      "managed": false,
      "status": "starting",
      "lastUpdated": "2019-10-01T02:09:53+0000",
      "owner": {
        "id": 1
      },
      "totalCpuUsage": 0,
      "stats": {
      }
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves deployments of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/deployments

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load deployments which contain the phrase specified
resourceLevel Resource level filter: app, system, storage, logging

Get Jobs

curl "$serverUrl/api/clusters/:id/jobs" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "jobs": [
    {
      "id": 5,
      "name": "Job 1",
      "type": "morpheus.task",
      "status": null,
      "namespace": null,
      "category": "kubernetes.job.cluster.3",
      "description": null,
      "enabled": true,
      "dateCreated": "2019-09-29T19:51:37+0000",
      "lastUpdated": "2019-09-29T20:00:58+0000",
      "lastRun": null,
      "createdBy": {
        "id": 1,
        "username": "root"
      }
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves jobs of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/jobs

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load jobs which contain the phrase specified

Get Pods

curl "$serverUrl/api/clusters/:id/pods" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "pods": [
    {
      "id": 30,
      "name": "test pod display name",
      "code": "test_pod_code",
      "description": null,
      "category": "kubernetes.pod.cluster.3",
      "resourceLevel": null,
      "resourceType": "pod",
      "managed": false,
      "status": "unknown",
      "lastUpdated": "2019-10-01T00:29:07+0000",
      "owner": {
        "id": 1
      },
      "totalCpuUsage": 0,
      "stats": {
      }
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves pods of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/pods

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load pods which contain the phrase specified
resourceLevel Resource level filter: app, system, storage, logging

Get Services

curl "$serverUrl/api/clusters/:id/services" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "services": [
    {
      "id": 5,
      "name": "test service",
      "type": null,
      "code": null,
      "externalIp": null,
      "internalIp": null,
      "externalPort": null,
      "internalPort": null,
      "status": null,
      "dateCreated": null,
      "lastUpdated": null
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves services of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/services

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load services which contain the phrase specified

Get Stateful Sets

curl "$serverUrl/api/clusters/:id/statefulsets" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "statefulsets": [    
    {
      "id": 3,
      "name": "test statefulset display name",
      "code": "test_code",
      "description": null,
      "category": "kubernetes.statefulset.cluster.3",
      "resourceLevel": null,
      "resourceType": "statefulset",
      "managed": false,
      "status": "starting",
      "lastUpdated": "2019-10-01T02:10:32+0000",
      "owner": {
        "id": 1
      },
      "totalCpuUsage": 0,
      "stats": {
      }
    }  
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves stateful sets of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/statefulsets

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name or internalId filter, restricts query to only load stateful sets which contain the phrase specified
resourceLevel Resource level filter: app, system, storage, logging

Delete Container

curl -XDELETE "$serverUrl/api/clusters/:clusterId/containers/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a container from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/containers/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the container to delete

Query Parameters

Parameter Default Description
force off Force Delete

Delete a Deployment

curl -XDELETE "$serverUrl/api/clusters/:clusterId/deployments/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a deployment from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/deployments/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the deployment to delete

Query Parameters

Parameter Default Description
force off Force Delete

Delete a Job

curl -XDELETE "$serverUrl/api/clusters/:clusterId/jobs/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a job from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/jobs/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the job to delete

Query Parameters

Parameter Default Description
force off Force Delete

Delete a Service

curl -XDELETE "$serverUrl/api/clusters/:clusterId/services/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a service from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/services/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the service to delete

Query Parameters

Parameter Default Description
force off Force Delete

Delete a Stateful Set

curl -XDELETE "$serverUrl/api/clusters/:clusterId/statefulsets/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a stateful set from the specified cluster

HTTP Request

DELETE $serverUrl/api/clusters/:clusterId/statefulsets/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the stateful set to delete

Query Parameters

Parameter Default Description
force off Force Delete

Restart a Container

curl -XPUT "$serverUrl/api/clusters/:clusterId/containers/:id/restart" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will restart a container in the specified cluster

HTTP Request

PUT $serverUrl/api/clusters/:clusterId/containers/:id/restart

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the container to restart

Restart a Deployment

curl -XPUT "$serverUrl/api/clusters/:clusterId/deployments/:id/restart" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will restart a deployment in the specified cluster

HTTP Request

PUT $serverUrl/api/clusters/:clusterId/deployments/:id/restart

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the deployment to restart

Restart a Pod

curl -XPUT "$serverUrl/api/clusters/:clusterId/pods/:id/restart" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will restart a pod in the specified cluster

HTTP Request

PUT $serverUrl/api/clusters/:clusterId/pods/:id/restart

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the pod to restart

Restart a Stateful Set

curl -XPUT "$serverUrl/api/clusters/:clusterId/statefulsets/:id/restart" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will restart a stateful set in the specified cluster

HTTP Request

PUT $serverUrl/api/clusters/:clusterId/statefulsets/:id/restart

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the stateful set to restart

Get Cluster History

curl "$serverUrl/api/clusters/:clusterId/history" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "processes": [
    {
      "id": 250,
      "accountId": 1,
      "uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
      "processType": {
        "code": "provision",
        "name": "provision"
      },
      "description": null,
      "subType": null,
      "subId": null,
      "zoneId": 34,
      "integrationId": null,
      "instanceId": 238,
      "containerId": 240,
      "serverId": 601,
      "containerName": "apachetest",
      "displayName": "apachetest",
      "timerCategory": "vmware",
      "timerSubCategory": "28",
      "status": "failed",
      "reason": null,
      "percent": 100.0,
      "statusEta": 348246,
      "message": null,
      "output": null,
      "error": null,
      "startDate": "2018-09-28T19:10:56+0000",
      "endDate": "2018-09-28T20:21:49+0000",
      "duration": 4253127,
      "dateCreated": "2018-09-28T19:10:56+0000",
      "lastUpdated": "2018-09-28T20:21:49+0000",
      "createdBy": {
        "username": "admin",
        "displayName": "Admin"
      },
      "updatedBy": {
        "username": "admin",
        "displayName": "Admin"
      },
      "events": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves the process history for a specific cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/history

Get Cluster History Details

curl "$serverUrl/api/clusters/:clusterId/history/:processId" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "process": {
    "id": 7,
    "accountId": 1,
    "uniqueId": "17bac5a4-b417-4004-ad5a-d05d16c42757",
    "processType": {
      "code": "serverProvision",
      "name": "server provision"
    },
    "description": null,
    "subType": null,
    "subId": null,
    "zoneId": null,
    "integrationId": null,
    "instanceId": null,
    "containerId": null,
    "serverId": 12,
    "containerName": null,
    "displayName": "kube1-master",
    "timerCategory": "amazonKubeMaster.provision",
    "timerSubCategory": null,
    "status": "complete",
    "reason": null,
    "percent": 100.0,
    "statusEta": 23108,
    "message": null,
    "output": null,
    "error": null,
    "startDate": "2019-07-29T23:40:56+0000",
    "endDate": "2019-07-29T23:41:19+0000",
    "duration": 22785,
    "dateCreated": "2019-07-29T23:40:56+0000",
    "lastUpdated": "2019-07-29T23:41:19+0000",
    "createdBy": {
      "username": "root",
      "displayName": "Stubby Toes"
    },
    "updatedBy": {
      "username": "root",
      "displayName": "Stubby Toes"
    },
    "events": [

    ]
  }
}

This endpoint retrieves the history for a specific cluster process.

HTTP Request

GET $serverUrl/api/clusters/:clusterId/history/:processId

Get Cluster History Event

curl "$serverUrl/api/clusters/:clusterId/history/events/:eventId" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "processEvent": {
    "id": 6,
    "processId": 125,
    "accountId": 1,
    "uniqueId": "f1ec503c-365a-4002-8fc5-2c0f3e9121d1",
    "processType": {
      "code": "provisionImage",
      "name": "prepare image"
    },
    "description": null,
    "refType": "computeServer",
    "refId": 129,
    "subType": null,
    "subId": null,
    "zoneId": null,
    "integrationId": null,
    "instanceId": null,
    "containerId": null,
    "serverId": 129,
    "containerName": null,
    "displayName": "dans-docker-host-2",
    "status": "failed",
    "reason": null,
    "percent": 100.0,
    "statusEta": 180000,
    "message": "failed to provision server",
    "output": null,
    "error": null,
    "startDate": "2019-09-25T17:49:23+0000",
    "endDate": "2019-09-25T17:49:43+0000",
    "duration": 20199,
    "dateCreated": "2019-09-25T17:49:23+0000",
    "lastUpdated": "2019-09-25T17:50:56+0000",
    "createdBy": {
      "username": "root",
      "displayName": "Stubby Toes"
    },
    "updatedBy": {
      "username": "root",
      "displayName": "Stubby Toes"
    }
  }
}

This endpoint retrieves the process event for a specific cluster process event.

HTTP Request

GET $serverUrl/api/clusters/:clusterId/history/events/:eventId

Get Datastores

curl "$serverUrl/api/clusters/:id/datastores"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "datastores": [
    {
      "id": 4,
      "name": "vsanDatastore",
      "code": null,
      "type": "vsan",
      "visibility": "privates",
      "storageSize": 3000483446784,
      "freeSpace": 1634729396798,
      "drsEnabled": false,
      "active": true,
      "allowWrite": true,
      "defaultStore": false,
      "online": true,
      "allowRead": true,
      "allowProvision": true,
      "refType": "ComputeServerGroup",
      "refId": 3,
      "externalId": "datastore-58601",
      "zone": {
        "id": 4
      },
      "zonePool": {
        "id": 9
      },
      "owner": {
        "id": 1
      },
      "tenants": [
        {
          "id": 1,
          "name": "Stubby Toes Inc."
        }
      ],
      "datastores": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves datastores of a specified cluster.

HTTP Request

GET $serverUrl/api/clusters/:id/datastores

URL Parameters

Parameter Description
id The ID of the cluster

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
order asc Sort direction, use 'desc’ to reverse sort
phrase Name filter, restricts query to only load datastores which contain the phrase specified
name Name filter, restricts query to only load datastore of specified name
code Code filter, restricts query to only load datastore of specified code
hideInactive false If true restricts query to only load active datastores

Get a Specific Datastore

curl "$serverUrl/api/clusters/1/datastores/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "datastore": {
    "id": 4,
    "name": "vsanDatastore",
    "code": null,
    "type": "vsan",
    "visibility": "privates",
    "storageSize": 3000483446784,
    "freeSpace": 1634729396798,
    "drsEnabled": false,
    "active": true,
    "allowWrite": true,
    "defaultStore": false,
    "online": true,
    "allowRead": true,
    "allowProvision": true,
    "refType": "ComputeServerGroup",
    "refId": 3,
    "externalId": "datastore-58601",
    "zone": {
      "id": 4
    },
    "zonePool": {
      "id": 9
    },
    "owner": {
      "id": 1
    },
    "tenants": [
      {
        "id": 1,
        "name": "Stubby Toes Inc."
      }
    ],
    "permissions": {
      "resourcePermissions": {
        "allGroups": true,
        "defaultStore": false,
        "allPlans": false,
        "defaultTarget": false,
        "morpheusResourceType": "Datastore",
        "morpheusResourceId": 4,
        "canManage": false,
        "all": true,
        "account": {
          "id": 1
        },
        "sites": [],
        "plans": []
      },
      "tenantPermissions": {
        "accounts": [           
          1
        ]
      }
    },
    "datastores": [

    ]
  }
}

This endpoint retrieves a specific cluster datastore.

HTTP Request

GET $serverUrl/api/clusters/:clusterId/datastores/:id

URL Parameters

Parameter Description
Cluster ID ID of the cluster
ID ID of datastore

Update Datastore

curl -XPUT "$serverUrl/api/clusters/1/datastores/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"datastore": {
        "active": true,
        "permissions": {
          "resourcePermissions": {
            "all": true,
            "sites": [
              {
                "id": 2
              }
            ]
          },
          "tenantPermissions": {
            "accounts": [
              1
            ]
          }
        },
        "visibility": "private" 
      }}'

The above command returns same JSON structure Get Datastore

HTTP Request

PUT $serverUrl/api/clusters/:clusterId/datastores/:id

URL Parameters

Parameter Description
clusterId The ID of the cluster
id The ID of the datastore

JSON Cluster Parameters

Parameter Required Default Description
visibility N private Visibility for datastore
active N true Datastore active
permissions N Key for resource permission configuration, see Permissions

Hosts

A Host, or Server, is either a bare metal machine or virtual machine that is provisioned into Morpheus via Chef. These servers are setup as Docker Hosts and used to provision containers into. They also run the morphd agent which reports host statistics and logs back to the Morpheus stack.

A Host may also be referred to as a Server or server.

Get All Hosts

curl "$serverUrl/api/servers"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "servers": [
    {
      "id": 2809,
      "uuid": "01548a80-9c98-49b0-9d36-f438e6557156",
      "externalId": "i-0ca3df01d3ea194eb",
      "internalId": null,
      "externalUniqueId": null,
      "name": "test-nginx",
      "externalName": "test-nginx",
      "hostname": "test-nginx",
      "accountId": 1,
      "account": {
        "id": 1,
        "name": "root"
      },
      "owner": {
        "id": 1,
        "username": "admin"
      },
      "zone": {
        "id": 39,
        "name": "test-aws"
      },
      "plan": {
        "id": 1,
        "code": "amazon-t2.nano",
        "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
      },
      "computeServerType": {
        "id": 45,
        "code": "amazonVm",
        "name": "Amazon Instance",
        "managed": true,
        "externalDelete": true
      },
      "visibility": "private",
      "description": null,
      "zoneId": 39,
      "siteId": 1,
      "resourcePoolId": 175,
      "folderId": null,
      "sshHost": null,
      "sshPort": 22,
      "externalIp": null,
      "internalIp": "172.31.3.206",
      "volumeId": null,
      "platform": "ubuntu",
      "platformVersion": "14.04",
      "sshUsername": "admin",
      "sshPassword": "************",
      "osDevice": "/dev/xvda",
      "osType": "linux",
      "dataDevice": "/dev/sdb",
      "lvmEnabled": false,
      "apiKey": "cc58b29b-278b-4847-a001-0295e2f6c897",
      "softwareRaid": false,
      "dateCreated": "2020-09-15T20:24:31Z",
      "lastUpdated": "2021-01-22T17:20:34Z",
      "stats": {
        "ts": "2021-01-22T17:20:34Z",
        "maxMemory": 536870912,
        "usedMemory": 0,
        "maxStorage": 10737418240,
        "usedStorage": 1423470592,
        "cpuUsage": 0.0,
        "freeMemory": 536870912,
        "netTxUsage": 0,
        "netRxUsage": 0,
        "networkBandwidth": 0
      },
      "status": "provisioned",
      "statusMessage": null,
      "errorMessage": null,
      "statusDate": "2020-09-15T20:24:58Z",
      "statusPercent": null,
      "statusEta": null,
      "powerState": "off",
      "agentInstalled": true,
      "lastAgentUpdate": "2020-11-02T16:11:58Z",
      "agentVersion": "2.0.0",
      "maxCores": 1,
      "maxMemory": 536870912,
      "maxStorage": 10737418240,
      "maxCpu": null,
      "hourlyCost": 0.0086816667,
      "hourlyPrice": 0.0086816667,
      "sourceImage": {
        "id": 99,
        "code": "amazon.ec2.image.morpheus.nginx.1.9",
        "name": "ubuntu-14_04-nginx-1_9-morph.0.1"
      },
      "serverOs": {
        "id": 5,
        "code": "ubuntu.14.04.64",
        "name": "ubuntu 14 64-bit",
        "description": null,
        "vendor": "canonical",
        "category": "ubuntu",
        "osFamily": "debian",
        "osVersion": "14.04",
        "bitCount": 64,
        "platform": "linux"
      },
      "serverOs": {
        "id": 50,
        "code": "linux",
        "name": "linux",
        "description": null,
        "vendor": "linux",
        "category": "linux",
        "osFamily": null,
        "osVersion": "all",
        "bitCount": 64,
        "platform": "linux"
      },
      "volumes": [
        {
          "id": 164967,
          "name": "root",
          "controllerId": null,
          "controllerMountPoint": null,
          "resizeable": true,
          "rootVolume": true,
          "unitNumber": null,
          "typeId": 14,
          "configurableIOPS": false,
          "datastoreId": null,
          "maxStorage": 32212254720,
          "displayOrder": 0,
          "maxIOPS": null
        }
      ],
      "controllers": [

      ],
      "interfaces": [
        {
          "refType": null,
          "refId": null,
          "name": "eth0",
          "internalId": null,
          "externalId": "eni-040163be55f537561",
          "uniqueId": "morpheus-nic-346-502-0",
          "publicIpAddress": "52.53.211.255",
          "publicIpv6Address": null,
          "ipAddress": "172.31.3.206",
          "ipv6Address": null,
          "ipSubnet": null,
          "ipv6Subnet": null,
          "description": "",
          "dhcp": true,
          "active": true,
          "poolAssigned": false,
          "primaryInterface": true,
          "network": null,
          "subnet": null,
          "networkGroup": null,
          "networkPosition": null,
          "networkPool": null,
          "networkDomain": null,
          "type": {
            "id": 1,
            "code": "standard",
            "name": "standard"
          },
          "ipMode": null,
          "macAddress": "06:d9:0e:f2:d3:01"
        }
      ],
      "labels": [

      ],
      "tags": [
        {
          "id": 43144,
          "name": "foo",
          "value": "bar"
        },
        {
          "id": 43143,
          "name": "hello",
          "value": "world"
        }
      ],
      "enabled": true,
      "tagCompliant": null,
      "containers": [
        502
      ]
    }
  ],
  "stats": {
    "2809": {
      "usedStorage": 1423470592,
      "reservedStorage": 10737418240,
      "maxStorage": 10737418240,
      "usedMemory": 0,
      "reservedMemory": 512217088,
      "maxMemory": 512217088,
      "cpuUsage": 0
    }
  },
  "multiTenant": true,
  "meta": {
    "max": 25,
    "offset": 0,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves a paginated list of hosts.

HTTP Request

GET $serverUrl/api/servers

Query Parameters

Parameter Default Description
name Filter by name
phrase Filter by wildcard search of name and description
zoneId Filter by zone (cloud) ID
siteId Filter by site (group) ID, restricts results to clouds in the specified group(s)
clusterId Filter by cluster ID
managed Filter by managed (true) or unmanaged (false)
serverType Filter by server type code
powerState Filter by power status
ip Filter by IP address
vm Filter to show only Virtual Machines (true)
vmHypervisor Filter to show only VM Hypervisors (true)
bareMetalHost Filter to show only Baremetal Servers (true)
status Filter by status
agentInstalled Filter by agent installed (true)
max 25 Max number of results to return
offset 0 Offset of records you want to load
lastUpdated Date filter, restricts query to only load servers updated timestamp is more recent or equal to the date specified
createdBy Filter by Created By (User) ID. Accepts multiple values.
tags Filter by tags (metadata). This allows filtering by arbitrary tag names and values like this tags.foo=bar.
metadata Alias for tags
uuid Filter by UUID
externalId Filter by External ID
internalId Filter by Internal ID
externalUniqueId Filter by External Unique ID

Get a Specific Host

curl "$serverUrl/api/servers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "server": {
    "id": 2809,
    "uuid": "01548a80-9c98-49b0-9d36-f438e6557156",
    "externalId": "i-0ca3df01d3ea194eb",
    "internalId": null,
    "externalUniqueId": null,
    "name": "test-nginx",
    "externalName": "test-nginx",
    "hostname": "test-nginx",
    "accountId": 1,
    "account": {
      "id": 1,
      "name": "root"
    },
    "owner": {
      "id": 1,
      "username": "admin"
    },
    "zone": {
      "id": 39,
      "name": "test-aws"
    },
    "plan": {
      "id": 1,
      "code": "amazon-t2.nano",
      "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
    },
    "computeServerType": {
      "id": 45,
      "code": "amazonVm",
      "name": "Amazon Instance",
      "managed": true,
      "externalDelete": true
    },
    "visibility": "private",
    "description": null,
    "zoneId": 39,
    "siteId": 1,
    "resourcePoolId": 175,
    "folderId": null,
    "sshHost": null,
    "sshPort": 22,
    "externalIp": null,
    "internalIp": "172.31.3.206",
    "volumeId": null,
    "platform": "ubuntu",
    "platformVersion": "14.04",
    "sshUsername": "admin",
    "sshPassword": "************",
    "osDevice": "/dev/xvda",
    "osType": "linux",
    "dataDevice": "/dev/sdb",
    "lvmEnabled": false,
    "apiKey": "cc58b29b-278b-4847-a001-0295e2f6c897",
    "softwareRaid": false,
    "dateCreated": "2020-09-15T20:24:31Z",
    "lastUpdated": "2021-01-22T17:15:10Z",
    "stats": {
      "ts": "2021-01-22T17:15:09Z",
      "maxMemory": 536870912,
      "usedMemory": 0,
      "maxStorage": 10737418240,
      "usedStorage": 1423470592,
      "cpuUsage": 0.0,
      "freeMemory": 536870912,
      "netTxUsage": 0,
      "netRxUsage": 0,
      "networkBandwidth": 0
    },
    "status": "provisioned",
    "statusMessage": null,
    "errorMessage": null,
    "statusDate": "2020-09-15T20:24:58Z",
    "statusPercent": null,
    "statusEta": null,
    "powerState": "off",
    "agentInstalled": true,
    "lastAgentUpdate": "2020-11-02T16:11:58Z",
    "agentVersion": "2.0.0",
    "maxCores": 1,
    "maxMemory": 536870912,
    "maxStorage": 10737418240,
    "maxCpu": null,
    "hourlyCost": 0.0086816667,
    "hourlyPrice": 0.0086816667,
    "sourceImage": {
      "id": 99,
      "code": "amazon.ec2.image.morpheus.nginx.1.9",
      "name": "ubuntu-14_04-nginx-1_9-morph.0.1"
    },
    "serverOs": {
      "id": 5,
      "code": "ubuntu.14.04.64",
      "name": "ubuntu 14 64-bit",
      "description": null,
      "vendor": "canonical",
      "category": "ubuntu",
      "osFamily": "debian",
      "osVersion": "14.04",
      "bitCount": 64,
      "platform": "linux"
    },
    "volumes": [
      {
        "id": 164967,
        "name": "root",
        "controllerId": null,
        "controllerMountPoint": null,
        "resizeable": true,
        "rootVolume": true,
        "unitNumber": null,
        "typeId": 14,
        "configurableIOPS": false,
        "datastoreId": null,
        "maxStorage": 32212254720,
        "displayOrder": 0,
        "maxIOPS": null
      }
    ],
    "controllers": [

    ],
    "interfaces": [
      {
        "refType": null,
        "refId": null,
        "name": "eth0",
        "internalId": null,
        "externalId": "eni-040163be55f537561",
        "uniqueId": "morpheus-nic-346-502-0",
        "publicIpAddress": "52.53.211.255",
        "publicIpv6Address": null,
        "ipAddress": "172.31.3.206",
        "ipv6Address": null,
        "ipSubnet": null,
        "ipv6Subnet": null,
        "description": "",
        "dhcp": true,
        "active": true,
        "poolAssigned": false,
        "primaryInterface": true,
        "network": null,
        "subnet": null,
        "networkGroup": null,
        "networkPosition": null,
        "networkPool": null,
        "networkDomain": null,
        "type": {
          "id": 1,
          "code": "standard",
          "name": "standard"
        },
        "ipMode": null,
        "macAddress": "06:d9:0e:f2:d3:01"
      }
    ],
    "labels": [

    ],
    "tags": [
      {
        "id": 43144,
        "name": "foo",
        "value": "bar"
      },
      {
        "id": 43143,
        "name": "hello",
        "value": "world"
      }
    ],
    "enabled": true,
    "tagCompliant": null,
    "containers": [
      502
    ],
    "config": {
      "isEC2": "false",
      "resourcePoolId": 175,
      "publicIpType": "subnet",
      "createUser": true
    }
  },
  "stats": {
    "usedStorage": 1423470592,
    "reservedStorage": 10737418240,
    "maxStorage": 10737418240,
    "usedMemory": 0,
    "reservedMemory": 512217088,
    "maxMemory": 512217088,
    "cpuUsage": 0
  }
}

This endpoint retrieves a specific host.

HTTP Request

GET $serverUrl/api/servers/:id

URL Parameters

Parameter Description
ID ID of the check to retrieve

Get Available Service Plans for a Host

curl -XGET "$serverUrl/api/servers/service-plans?zoneId=2&serverTypeId=60" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "plans": [
    {
      "id": 75,
      "name": "1 CPU, 512MB Memory",
      "value": 75,
      "code": "vm-512",
      "maxStorage": 10737418240,
      "maxMemory": 536870912,
      "maxCpu": 1,
      "maxCores": 1,
      "customCpu": false,
      "customMaxMemory": false,
      "customMaxStorage": true,
      "customMaxDataStorage": true,
      "customCoresPerSocket": false,
      "coresPerSocket": 1,
      "storageTypes": [
        {
          "id": 1,
          "editable": false,
          "optionTypes": [

          ],
          "displayOrder": 1,
          "code": "standard",
          "volumeType": "disk",
          "minStorage": null,
          "deletable": false,
          "defaultType": true,
          "createDatastore": null,
          "resizable": false,
          "storageType": null,
          "allowSearch": true,
          "volumeOptionSource": null,
          "displayName": "Disk",
          "minIOPS": null,
          "maxIOPS": null,
          "hasDatastore": true,
          "customSize": true,
          "autoDelete": true,
          "name": "Standard",
          "configurableIOPS": false,
          "customLabel": true,
          "enabled": true,
          "description": "Standard",
          "volumeCategory": "disk",
          "externalId": null,
          "maxStorage": null
        }
      ],
      "rootStorageTypes": [
        {
          "id": 1,
          "editable": false,
          "optionTypes": [

          ],
          "displayOrder": 1,
          "code": "standard",
          "volumeType": "disk",
          "minStorage": null,
          "deletable": false,
          "defaultType": true,
          "createDatastore": null,
          "resizable": false,
          "storageType": null,
          "allowSearch": true,
          "volumeOptionSource": null,
          "displayName": "Disk",
          "minIOPS": null,
          "maxIOPS": null,
          "hasDatastore": true,
          "customSize": true,
          "autoDelete": true,
          "name": "Standard",
          "configurableIOPS": false,
          "customLabel": true,
          "enabled": true,
          "description": "Standard",
          "volumeCategory": "disk",
          "externalId": null,
          "maxStorage": null
        }
      ],
      "addVolumes": true,
      "customizeVolume": true,
      "rootDiskCustomizable": true,
      "noDisks": false,
      "hasDatastore": true,
      "minDisk": 0,
      "maxDisk": null,
      "lvmSupported": true,
      "datastores": {
        "cluster": [
          {
            "id": 54,
            "name": "demo-qnap - 4.3TB Free"
          }
        ],
        "store": [
          {
            "id": 50,
            "name": "datastore1 - 463.4GB Free"
          }
        ]
      },
      "supportsAutoDatastore": true,
      "autoOptions": [
        {
          "id": "autoCluster",
          "name": "Auto - Cluster"
        },
        {
          "id": "auto",
          "name": "Auto - Datastore"
        }
      ],
      "cpuOptions": [

      ],
      "coreOptions": [

      ],
      "memoryOptions": [

      ],
      "rootCustomSizeOptions": {
      },
      "customSizeOptions": {
      },
      "customCores": false,
      "maxDisks": null,
      "memorySizeType": "MB"
    }
  ]
}

This endpoint retrieves all the Service Plans available for the specified cloud and host type. It may be used to get the list of available plans when creating a new host or resizing an existing host.

HTTP Request

GET $serverUrl/api/servers/service-plans?zoneId=:zoneId&serverTypeId=:serverTypeId&siteId=:siteId

Query Parameters

Parameter Required Description
zoneId The ID of the Cloud
serverTypeId Y The ID of the Host Type
siteId N The ID of the Group

Provision a Host

curl -XPOST "$serverUrl/api/servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "server": {
  "name": "my-nginx",
  "description": "my-nginx",
  "zone": {"id":1},
  "sshHost": "10.100.54.4",
  "sshUsername": "vagrant",
  "sshPassword": "T8Hqq=cJhb*#",
  "dataDevice": "/dev/sdb"
  },
  "network": {
    "name": "eth1"
  }
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

POST $serverUrl/api/servers

JSON Server Parameters

Parameter Default Description
name Unique name scoped to your account for the server
description Optional description field
zone The zone id we want to assign the server to.
sshHost reachable ip address for the server to remote in and provision the server
sshUsername ssh username to use when provisioning
sshPassword optional ssh password to use, if not specified the account public key can be used
dataDevice the mount point for the lvm volume that needs to be created

Updating a Host

curl -XPUT "$serverUrl/api/servers/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "server": {
  "name": "my-nginx",
  "description": "my-nginx",
  "addTags": [
    {"name": "hello", "value": "world"}
  ],
  "removeTags": [
    {"name": "oldTag"}
  ]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a specific host

HTTP Request

PUT $serverUrl/api/servers/:id

JSON Server Parameters

Parameter Default Description
name Unique name scoped to your account for the server
description Optional description field
sshUsername SSH Username
sshPassword SSH Password
powerScheduleType Power Schedule ID
tags Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified.
addTags Add or update value of Metadata tags, Array of objects having a name and value
removeTags Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed.

Convert To Managed

curl -XPUT "$serverUrl/api/servers/1/make-managed" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "sshUsername": "admin",
      "sshPassword": "93KL_&Tdst!e",
      "serverOs": {"id": 1},
      "plan": {"id": 9},
      "account": {"id": 1},
      "tags": [
        {"name": "hello", "value": "world"},
        {"name": "flash", "value": "bang"}
      ],
      "config": {
        "customOptions": {
          "dbfoldername": "data"
        }
      }
    }, 
    "installAgent": true
  }
'

The above command returns JSON structure like this:

{
  "success": true
}

This will make the host a managed server, and install the agent.

HTTP Request

PUT $serverUrl/api/servers/:id/make-managed

JSON Parameters

Parameter Default Description
server Object containing server configuration parameters
installAgent true Install agent. Set to false to manually install agent instead.
instanceTypeId Specific instance type ID to assign the server
layout Specific layout ID to assign the server (required if instanceTypeId is passed)

JSON Server Parameters

Parameter Default Description
sshUsername ssh username to use when provisioning
sshPassword ssh password to use, if not specified the account public key can be used
serverOs.id The ID os the OS Type for this server. See GET /api/options/osTypes
plan.id Service Plan to assign to the server
account.id Tenant to assign the server to. Only available to Master Tenant users/
provisionSiteId Specific group to assign the server
tags Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified.
config.customOptions Custom Option Type settings object containing name value pairs to be set.

Upgrade Agent

curl -XPUT "$serverUrl/api/servers/1/upgrade" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will upgrade the version of the install installed on the host.

HTTP Request

PUT $serverUrl/api/servers/:id/upgrade

Resize a Host

curl -XPUT "$serverUrl/api/servers/1/resize" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "id": 82,
      "plan": {
        "id": 76
      }
    },
    "volumes": [
      {
        "id": 419,
        "rootVolume": true,
        "name": "root",
        "size": 10,
        "sizeId": null,
        "storageType": 1,
        "datastoreId": "auto"
      }
    ],
    "deleteOriginalVolumes": true,
    "servicePlanOptions": {
      "maxCores": 1,
      "coresPerSocket": 1,
      "maxMemory": 536870912
    },
    "networkInterfaces": [
      {
        "id": 612,
        "name": "eth0",
        "network": {
          "id": "network-22"
        }
      },
      {
        "name": "eth1",
        "network": {
          "id": "network-22"
        }
      }
    ]
  }'

The above command returns JSON structure like this:

{
  "success": true
}

Will resize a host asynchronously. This endpoint also allows for NIC reconfiguration by passing a new array of networkInterfaces.

HTTP Request

PUT $serverUrl/api/servers/:id/resize

JSON Server Parameters

Parameter Default Description
server.plan.id The ID of the new plan (optional). See Available Service Plans
servicePlanOptions Map of custom options depending on selected service plan.
servicePlanOptions.maxCores Core Count
servicePlanOptions.coresPerSocket Cores Per Socket
servicePlanOptions.maxMemory Memory in bytes For backwards compatability, values less than 1048576 are treated as being in MB and will be converted to bytes
volumes List of volumes with their new sizes, see Volumes.
deleteOriginalVolumes false Delete the original volumes after resizing. (Amazon only)
networkInterfaces Key for network configuration, see Network Interfaces. Include id to update an existing interface.

Start a Host

curl -X PUT "$serverUrl/api/servers/1/start" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will start a host.

HTTP Request

PUT $serverUrl/api/servers/:id/start

URL Parameters

Parameter Description
:id ID of the server

Stop a Host

curl -X PUT "$serverUrl/api/servers/1/stop" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This will stop a host.

HTTP Request

PUT $serverUrl/api/servers/:id/stop

URL Parameters

Parameter Description
:id ID of the server

Run Workflow on a Host

curl -X PUT "$serverUrl/api/servers/1/workflow?workflowId=33" \
  -H "Authorization: BEARER $accessToken" \
  -d '{ "taskSet": {
    "customOptions": {"mysqlVersion":"5.6.17"}
    }}'

The above command returns JSON structure like this:

{
  "success": true
}

This will run a provisioning workflow on a host.

For operational workflows, see Execute a Workflow.

HTTP Request

PUT $serverUrl/api/servers/:id/workflow

URL Parameters

Parameter Description
:id ID of the server

Query Parameters

Parameter Description
workflowId ID of the workflow to execute
workflowName Name of the workflow to execute

JSON Parameters

Parameter Default Description
taskSet Object containing workflow configuration parameters
taskSet.customOptions Object containing any custom option type configuration parameters

Get list of snapshots for a Host

curl "$serverUrl/api/servers/:id/snapshots" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure that looks like this:

{
    "snapshots": [
    ]
}

HTTP Request

GET $serverUrl/api/servers/:id/snapshots

URL Parameters

Parameter Description
:id ID of the server

Assign To Tenant

curl -XPUT "$serverUrl/api/servers/1/assign-account?accountId=2" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON structure like this:

{
  "success": true
}

This will change the ownership of the host to the specified Tenant account. This is only available to Master Tenant users.

HTTP Request

PUT $serverUrl/api/servers/:id/assign-account?accountId=:accountId

URL Parameters

Parameter Description
:id ID of the Server

URL Parameters

Parameter Description
:accountId ID of the Tenant

Delete a Host

curl -XDELETE "$serverUrl/api/servers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a host asynchronously.

HTTP Request

DELETE $serverUrl/api/servers/:id

Query Parameters

Parameter Default Description
removeResources on if server is managed. Remove Infrastructure.
removeInstances off Remove Associated Instances
preserveVolumes off Preserve Volumes
releaseEIPs on Release EIPs
force off Force Delete

Host Types

Fetch a paginated list of available host types. This returns the configuration options for each type.

curl "$serverUrl/api/server-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "serverTypes":[
    {
      "id":19,
      "code":"softlayerVm",
      "name":"Softlayer Instance",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-vm-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":0,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":false,
      "optionTypes":[

      ]
    },
    {
      "id":23,
      "code":"amazonVm",
      "name":"Amazon Instance",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-vm-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":0,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":false,
      "optionTypes":[

      ]
    },
    {
      "id":31,
      "code":"vmwareVm",
      "name":"Vmware Instance",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-vm-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":0,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":false,
      "optionTypes":[

      ]
    },
    {
      "id":39,
      "code":"nutanixVm",
      "name":"Nutanix Instance",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-vm-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":0,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":false,
      "optionTypes":[

      ]
    },
    {
      "id":43,
      "code":"xenserverVm",
      "name":"Xen Instance",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-vm-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":0,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":false,
      "optionTypes":[

      ]
    },
    {
      "id":14,
      "code":"metapodLinux",
      "name":"Metapod Linux Node",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":2,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":true,
      "optionTypes":[

      ]
    },
    {
      "id":8,
      "code":"openstackLinux",
      "name":"Openstack Linux Node",
      "description":"",
      "platform":"linux",
      "nodeType":"morpheus-node",
      "managed":true,
      "enabled":true,
      "vmHypervisor":false,
      "containerHypervisor":false,
      "displayOrder":4,
      "selectable":false,
      "controlPower":true,
      "controlSuspend":true,
      "hasAgent":true,
      "creatable":true,
      "optionTypes":[
        {
          "name":"osUsr",
          "type":"text",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"osUsr",
          "fieldContext":"config"
        },
        {
          "name":"flavorId",
          "type":"selectOsFlavor",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"flavorId",
          "fieldContext":"config"
        },
        {
          "name":"imageId",
          "type":"selectOsImage",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"imageId",
          "fieldContext":"config"
        },
        {
          "name":"osNetworkId",
          "type":"selectOsNetwork",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"osNetworkId",
          "fieldContext":"config"
        },
        {
          "name":"diskSize",
          "type":"text",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"diskSize",
          "fieldContext":"config"
        },
        {
          "name":"templateTypeSelect",
          "type":"radio",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"templateTypeSelect",
          "fieldContext":"config"
        },
        {
          "name":"floatingIp",
          "type":"checkbox",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"floatingIp",
          "fieldContext":"config"
        },
        {
          "name":"osPwd",
          "type":"password",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"osPwd",
          "fieldContext":"config"
        },
        {
          "name":"diskMode",
          "type":"selectDiskMode",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"diskMode",
          "fieldContext":"config"
        },
        {
          "name":"securityGroup",
          "type":"selectOpenstackSecurityGroup",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"securityGroup",
          "fieldContext":"config"
        },
        {
          "name":"publicKeyId",
          "type":"keyPairSelect",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"publicKeyId",
          "fieldContext":"config"
        },
        {
          "name":"serverGroup",
          "type":"selectOpenstackServerGroup",
          "defaultValue":null,
          "placeHolder":null,
          "required":true,
          "fieldName":"serverGroup",
          "fieldContext":"config"
        }
      ]
    }
  ]
}

HTTP Request

GET $serverUrl/api/server-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort displayOrder Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
name Filter by name or code
code Filter by code
phrase Filter by wildcard search of name, code and description
provisionType Filter by Provision Type code
zoneType Filter by Zone Type code
creatable Filter by creatable flag. This is whether or not it can be provisioned.

Get a Specific Host Type

curl "$serverUrl/api/server-types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "serverType": {
    "id": 19,
    "code": "softlayerVm",
    "name": "Softlayer Instance",
    "description": "",
    "platform": "linux",
    "nodeType": "morpheus-vm-node",
    "managed": true,
    "enabled": true,
    "vmHypervisor": false,
    "containerHypervisor": false,
    "displayOrder": 0,
    "selectable": false,
    "controlPower": true,
    "controlSuspend": true,
    "hasAgent": true,
    "creatable": false,
    "optionTypes": []
  }
}

This endpoint will retrieve a specific host type by id

HTTP Request

GET $serverUrl/api/server-types/:id

URL Parameters

Parameter Description
ID The ID of the host type

Networks

Provides API for managing Networks.

Get All Networks

curl "$serverUrl/api/networks"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networks": [
    {
      "id": 1,
      "name": "my-network",
      "displayName": "my-displayName",
      "zone": {
        "id": 5,
        "name": "qa-azure"
      },
      "type": {
        "id": 8,
        "name": "Network",
        "code": "azureNetwork"
      },
      "owner": {
        "id": 1,
        "name": "root"
      },
      "code": null,
      "category": "azure.network.5",
      "interfaceName": null,
      "bridgeName": null,
      "bridgeInterface": null,
      "description": null,
      "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-f34622281a98/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/my-network",
      "internalId": null,
      "uniqueId": null,
      "externalType": "Network",
      "refUrl": null,
      "refType": "ComputeZone",
      "refId": 31,
      "vlanId": null,
      "vswitchName": null,
      "dhcpServer": true,
      "dhcpIp": null,
      "gateway": null,
      "netmask": null,
      "broadcast": null,
      "subnetAddress": null,
      "dnsPrimary": null,
      "dnsSecondary": null,
      "cidr": "192.168.0.0/16",
      "tftpServer": null,
      "bootFile": null,
      "switchId": null,
      "fabricId": null,
      "networkRole": null,
      "status": "available",
      "availabilityZone": null,
      "pool": null,
      "networkProxy": null,
      "networkDomain": null,
      "prefixLength": null,
      "visibility": "private",
      "enableAdmin": false,
      "active": true,
      "defaultNetwork": false,
      "assignPublicIp": false,
      "noProxy": null,
      "applianceUrlProxyBypass": true,
      "zonePool": {
        "id": 118,
        "name": "ARMUbuntu16"
      },
      "allowStaticOverride": false,
      "config": {
        "vlanIDs": null,
        "connectedGateway": "/infra/tier-1s/51b5f3c3-cc7e-4cef-89b5-dd576e8df454",
        "subnetIpManagementType": "dhcpLocal",
        "subnetIpServerId": "/infra/dhcp-server-configs/f1137d64-8402-41a2-abd8-7347743e5f4f",
        "dhcpRange": "192.168.123.10-192.168.123.100",
        "subnetDhcpServerAddress": "192.168.123.1/24",
        "subnetDhcpLeaseTime": "86400"
      },
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Networks associated with the account.

HTTP Request

GET $serverUrl/api/networks

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Network

curl "$serverUrl/api/networks/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "network": {
    "id": 1,
    "name": "my-network",
    "displayName" : "network display name",
    "zone": {
      "id": 31,
      "name": "qa-azure"
    },
    "type": {
      "id": 8,
      "name": "Network",
      "code": "azureNetwork"
    },
    "owner": {
      "id": 1,
      "name": "root"
    },
    "code": null,
    "category": "azure.network.31",
    "interfaceName": null,
    "bridgeName": null,
    "bridgeInterface": null,
    "description": null,
    "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-f34622281a98/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/my-network",
    "internalId": null,
    "uniqueId": null,
    "externalType": "Network",
    "refUrl": null,
    "refType": "ComputeZone",
    "refId": 31,
    "vlanId": null,
    "vswitchName": null,
    "dhcpServer": true,
    "dhcpIp": null,
    "gateway": null,
    "netmask": null,
    "broadcast": null,
    "subnetAddress": null,
    "dnsPrimary": null,
    "dnsSecondary": null,
    "cidr": "192.168.0.0/16",
    "tftpServer": null,
    "bootFile": null,
    "switchId": null,
    "fabricId": null,
    "networkRole": null,
    "status": "available",
    "availabilityZone": null,
    "pool": null,
    "networkProxy": null,
    "networkDomain": null,
    "prefixLength": null,
    "visibility": "private",
    "enableAdmin": false,
    "active": true,
    "defaultNetwork": false,
    "assignPublicIp": false,
    "noProxy": null,
    "applianceUrlProxyBypass": true,
    "zonePool": {
      "id": 118,
      "name": "ARMUbuntu16"
    },
    "allowStaticOverride": false,
    "config": {
      "vlanIDs": null,
      "connectedGateway": "/infra/tier-1s/51b5f3c3-cc7e-4cef-89b5-dd576e8df454",
      "subnetIpManagementType": "dhcpLocal",
      "subnetIpServerId": "/infra/dhcp-server-configs/f1137d64-8402-41a2-abd8-7347743e5f4f",
      "dhcpRange": "192.168.123.10-192.168.123.100",
      "subnetDhcpServerAddress": "192.168.123.1/24",
      "subnetDhcpLeaseTime": "86400"
    },
    "tenants": [
      {
        "id": 1,
        "name": "root"
      }
    ]
  }
}

This endpoint retrieves a specific Network.

HTTP Request

GET $serverUrl/api/networks/:id

URL Parameters

Parameter Description
ID The ID of the Network to retrieve

Create a Network

curl -XPOST "$serverUrl/api/networks" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "network": {
    "name": "test network",
    "displayName": "Network Display Name",
    "description": "a test network",
    "zone": {
      "id": 31
    },
    "type": {
      "id": 8
    },
    "resourceGroupId": "testresource",
    "addressSpace": "192.168.2.0/24",
    "subnetName": "test",
    "subnetCidr": "192.168.2.0/28",
    "scanNetwork": "off",
    "applianceUrlProxyBypass": "on",
    "noProxy": null,
    "resourcePermission": {
      "all": true
    },
    "config": {
      "vlanIDs": null,
      "connectedGateway": "/infra/tier-1s/51b5f3c3-cc7e-4cef-89b5-dd576e8df454",
      "subnetIpManagementType": "dhcpLocal",
      "subnetIpServerId": "/infra/dhcp-server-configs/f1137d64-8402-41a2-abd8-7347743e5f4f",
      "dhcpRange": "192.168.123.10-192.168.123.100",
      "subnetDhcpServerAddress": "192.168.123.1/24",
      "subnetDhcpLeaseTime": "86400"
    },
    "tenants": [
      {
        "id": 2
      },
      {
        "id": 1
      }
    ],
    "visibility": "private"
  }
}'

The above command returns JSON structured like getting a single Network:

HTTP Request

POST $serverUrl/api/networks

JSON Parameters

Parameter Default Description
name Name
displayName Display Name
description Description
zone.id Cloud ID
type.id Network Type ID
pool Network Pool ID
allowStaticOverride Allow IP Override
assignPublicIP Assign Public IP
active Activate (true) or disable (false) the network
availabilityZone Availability Zone
networkDomain.id Network Domain ID
searchDomains Search Domains
scanNetwork off Scan Network
networkProxy.id Network Proxy ID
applianceUrlProxyBypass on Bypass Proxy for Appliance URL
noProxy List of ip addresses or name servers to exclude proxy traversal for. Typically locally routable servers are excluded.
visibility private private or public
config Configuration object. Settings vary by type.
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

This endpoint allows creating a Network. Only certain types of clouds support creating and deleting networks. Configuration options vary by Network Types.

Update a Network

curl -XPUT "$serverUrl/api/networks/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "network": {
    "description": "a test network",
    "config": {
      "vlanIDs": null,
      "connectedGateway": "/infra/tier-1s/51b5f3c3-cc7e-4cef-89b5-dd576e8df454",
      "subnetIpManagementType": "dhcpLocal",
      "subnetIpServerId": "/infra/dhcp-server-configs/f1137d64-8402-41a2-abd8-7347743e5f4f",
      "dhcpRange": "192.168.123.10-192.168.123.100",
      "subnetDhcpServerAddress": "192.168.123.1/24",
      "subnetDhcpLeaseTime": "86400"
    }
  }
}'

The above command returns JSON structured like getting a single Network:

HTTP Request

PUT $serverUrl/api/networks/:id

URL Parameters

Parameter Description
ID The ID of the Network

JSON Parameters

Parameter Default Description
displayName Display Name
description Description
dhcpServer DHCP Server
allowStaticOverride Allow IP Override
assignPublicIP Assign Public IP
active Activate (true) or disable (false) the network
availabilityZone Availability Zone
scanNetwork off Scan Network
networkProxy.id Network Proxy ID
applianceUrlProxyBypass on Bypass Proxy for Appliance URL
noProxy List of ip addresses or name servers to exclude proxy traversal for. Typically locally routable servers are excluded.
visibility private private or public
config Configuration object. Settings vary by type.
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

This endpoint allows updating a Network. Configuration options vary by Network Types.

Delete a Network

curl -XDELETE "$serverUrl/api/networks/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/:id

URL Parameters

Parameter Description
ID The ID of the Network

Network DHCP Static Routes

Provides API interfaces for managing Network DHCP static routes for a Network within Morpheus.

Get all Static Routes for a Network

curl "$serverUrl/api/networks/1/routes" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRoutes": [
    {
      "id": 58,
      "name": "api-test-route3",
      "code": null,
      "description": null,
      "priority": null,
      "routeType": "static",
      "source": "10.10.0.0/24",
      "sourceType": "cidr",
      "destination": "10.20.0.0",
      "destinationType": "address",
      "defaultRoute": false,
      "networkMtu": null,
      "externalInterface": null,
      "internalId": null,
      "uniqueId": null,
      "externalType": null,
      "enabled": true,
      "visible": true
    }
  ]
}

This endpoint retrieves all routes for specified network.

HTTP Request

GET $serverUrl/api/networks/:network_id/routes

URL Parameters

Parameter Description
network_id The ID of the network

Get a Static Route for a Network

curl "$serverUrl/api/networks/1/routes/59" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRoute": {
    "id": 59,
    "name": "api-test-route3",
    "code": null,
    "description": null,
    "priority": null,
    "routeType": "static",
    "source": "10.10.0.0/24",
    "sourceType": "cidr",
    "destination": "10.20.0.0",
    "destinationType": "address",
    "defaultRoute": false,
    "networkMtu": null,
    "externalInterface": null,
    "internalId": null,
    "uniqueId": null,
    "externalType": null,
    "enabled": true,
    "visible": true
  }
}

This endpoint retrieves a network static route for specified network.

HTTP Request

GET $serverUrl/api/networks/:network_id/routes/:route_id

URL Parameters

Parameter Description
network_id The ID of the network
route_id The ID of the route

Create a Network Static Route

Use this command to create a route for an existing network.

curl -XPOST "$serverUrl/api/networks/1/routes" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRoute": {
          "source": "10.10.10.10/24",
          "destination": "12.12.12.12"
        }
      }'

The above command returns JSON Structured like this:

{
  "id": 43,
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/:network_id/routes/:route_id

URL Parameters

Parameter Description
network_id The ID of the network
route_id The ID of the route to be updated

JSON Parameters

Parameter Required Description
source Y Source CIDR
destination Y Destination address

Update a Network Static Route

Use this command to update a route

curl -XPUT "$serverUrl/api/networks/1/routes/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRoute": {
          "source": "10.10.10.10/24",
          "destination": "12.12.12.12"
        }
      }'

The above command returns JSON Structured like this:

{
  "id": 43,
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/:network_id/routes/:route_id

URL Parameters

Parameter Description
network_id The ID of the network
route_id The ID of the route to be updated

JSON Parameters

Parameter Required Description
source Y Source CIDR
destination Y Destination address

Delete a Network Static Route

curl -XDELETE "$serverUrl/api/networks/1/routes/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a route from a network.

HTTP Request

DELETE $serverUrl/api/networks/:network_id/routes/:route_id

URL Parameters

Parameter Description
network_id The ID of the network
route_id The ID of the route to be deleted

Network DHCP Servers

Provides API interfaces for managing Network DHCP Servers for a Network Service within Morpheus.

Get all Network DHCP Servers for Network Server

curl "$serverUrl/api/networks/servers/1/dhcp-servers" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "networkDhcpServers": [
        {
            "id": 5,
            "dateCreated": "2021-11-02T20:06:01Z",
            "providerId": "/infra/dhcp-server-configs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "serverIpAddress": "192.168.123.100/24",
            "lastUpdated": "2021-11-02T20:06:01Z",
            "leaseTime": 86400,
            "name": "test-dhcp-server",
            "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "config": {
                "edgeCluster": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "preferredEdgeNode1": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "preferredEdgeNode2": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            },
            "owner": {
                "id": 1
            },
            "networkServer": {
                "id": 5
            }
        }
    ],
    "meta": {
        "max": "25",
        "offset": "0",
        "sort": "name",
        "order": "asc",
        "total": 1
    }
}

This endpoint retrieves all Network DHCP Servers for a specified Network Service.

HTTP Request

GET $serverUrl/api/networks/servers/:id/dhcp-servers

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load Network DHCP Servers that contain the phrase specified in name or description

Get a Specific Network DHCP Server

curl "$serverUrl/api/networks/servers/1/dhcp-servers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "networkDhcpServer": {
      "id": 5,
      "dateCreated": "2021-11-02T20:06:01Z",
      "providerId": "/infra/dhcp-server-configs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "serverIpAddress": "192.168.123.100/24",
      "lastUpdated": "2021-11-02T20:06:01Z",
      "leaseTime": 86400,
      "name": "test-dhcp-server",
      "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "config": {
          "edgeCluster": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "preferredEdgeNode1": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "preferredEdgeNode2": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      },
      "owner": {
          "id": 1
      },
      "networkServer": {
          "id": 5
      }
    }
}

This endpoint retrieves a specific Network DHCP Server.

HTTP Request

GET $serverUrl/api/networks/servers/:serverId/dhcp-servers/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the Network DHCP Server

Create a Network DHCP Server

curl -XPOST "$serverUrl/api/networks/servers/1/dhcp-servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkDhcpServer": {
      "serverIpAddress": "192.168.123.100/24",
      "leaseTime": 86400,
      "name": "test-dhcp-server",
      "config": {
          "edgeCluster": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "preferredEdgeNode1": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "preferredEdgeNode2": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
}'

The above command returns JSON structured like getting a single Network DHCP Server:

{
  "success": true,
  "id": 7
}

HTTP Request

POST $serverUrl/api/networks/servers/:serverId/dhcp-servers

URL Parameters

Parameter Description
serverId ID of the network server

JSON Parameters

Parameter Default Description
name Name
serverIpAddress Server Address for the DHCP Server
leaseTime 86400 Optional lease time for the DHCP Server
config Configuration object with parameters that vary by pool type.

NSX-T Config Options

Parameter Required Description
edgeCluster N Edge Cluster See Edge Clusters
preferredEdgeNode1 N Active Edge Node Options obtained by calling option source with :optionSource = nsxtEdgeNodes and networkServerId param
preferredEdgeNode2 N Standby Edge Node Options obtained by calling option source with optionSource = nsxtEdgeNodes and networkServerId param

Update a Network DHCP Server

Use this command to update an existing Network DHCP Server.

curl -XPUT "$serverUrl/api/networks/servers/1/dhcp-servers/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
    "networkDhcpServer": {
          "id": 5,
          "dateCreated": "2021-11-02T20:06:01Z",
          "providerId": "/infra/dhcp-server-configs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "serverIpAddress": "192.168.123.100/24",
          "lastUpdated": "2021-11-02T20:06:01Z",
          "leaseTime": 86400,
          "name": "test-dhcp-server",
          "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "config": {
              "edgeCluster": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "preferredEdgeNode1": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "preferredEdgeNode2": "/infra/sites/default/enforcement-points/default/dhcp-servers/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/edge-nodes/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          },
          "owner": {
              "id": 1
          },
          "networkServer": {
              "id": 5
          }
        }
    }'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/servers/:serverId/dhcp-servers/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the Network DHCP Server

JSON Parameters

The parameters for update a Network DHCP Server is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Description
name Network DHCP Server name
description Network DHCP Server description

NSX-T Config Options

Parameter Required Description
edgeCluster N Edge Cluster See Edge Clusters
preferredEdgeNode1 N Active Edge Node Options obtained by calling option source with :optionSource = nsxtEdgeNodes and networkServerId param
preferredEdgeNode2 N Standby Edge Node Options obtained by calling option source with optionSource = nsxtEdgeNodes and networkServerId param

Delete a Network DHCP Server

curl -XDELETE "$serverUrl/api/networks/servers/:serverId/dhcp-servers/:id`
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network DHCP Server from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/servers/:serverId/dhcp-servers/:id

URL Parameters

Parameter Description
serverId ID of the network server
id The ID of the Network DHCP Server

Network DHCP Relays

Provides API interfaces for managing Network DHCP Relays for a Network Service within Morpheus.

Get all Network DHCP Relays for Network Server

curl "$serverUrl/api/networks/servers/1/dhcp-relays" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "networkDhcpRelays": [
        {
            "id": 5,
            "dateCreated": "2021-11-02T20:06:02Z",
            "providerId": "/infra/dhcp-relay-configs/test-dhcp-repay",
            "lastUpdated": "2021-11-08T21:30:07Z",
            "name": "test-dhcp-relay",
            "externalId": "test-dhcp-repay",
            "serverIpAddresses": [
                "192.168.127.128"
            ],
            "owner": {
                "id": 1
            },
            "networkServer": {
                "id": 5
            }
        }
    ],
    "meta": {
        "max": "25",
        "offset": "0",
        "sort": "name",
        "order": "asc",
        "total": 2
    }
}

This endpoint retrieves all Network DHCP Relays for a specified Network Service.

HTTP Request

GET $serverUrl/api/networks/servers/:id/dhcp-relays

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load Network DHCP Relays that contain the phrase specified in name or description

Get a Specific Network DHCP Relay

curl "$serverUrl/api/networks/servers/1/dhcp-relays/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "networkDhcpRelay": {
        "id": 5,
        "dateCreated": "2021-11-02T20:06:02Z",
        "providerId": "/infra/dhcp-relay-configs/dd-test-dhcp-repay",
        "lastUpdated": "2021-11-08T21:30:07Z",
        "name": "test-dhcp-relay",
        "externalId": "test-dhcp-repay",
        "serverIpAddresses": [
            "192.168.127.128"
        ],
        "owner": {
            "id": 1
        },
        "networkServer": {
            "id": 5
        }
    }
}

This endpoint retrieves a specific Network DHCP Relay.

HTTP Request

GET $serverUrl/api/networks/servers/:serverId/dhcp-relays/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the Network DHCP Relay

Create a Network DHCP Relay

curl -XPOST "$serverUrl/api/networks/servers/1/dhcp-relays" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkDhcpRelay": {
      "name": "test-dhcp-relay",
      "serverIpAddresses": [
          "192.168.127.129"
      ]
  }
}'

The above command returns JSON structured like getting a single Network DHCP Relay:

{
  "success": true,
  "id": 7
}

HTTP Request

POST $serverUrl/api/networks/servers/:serverId/dhcp-relays

URL Parameters

Parameter Description
serverId ID of the network server

JSON Parameters

Parameter Default Description
name Name
serverIpAddresses Server IP Addresses for the DHCP Relay

Update a Network DHCP Relay

Use this command to update an existing Network DHCP Relay.

curl -XPUT "$serverUrl/api/networks/servers/1/dhcp-relays/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
    "networkDhcpRelay": {
        "name": "test-dhcp-relay",
        "serverIpAddresses": [
            "192.168.127.129"
        ]
    }
    }'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/servers/:serverId/dhcp-relays/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the Network DHCP Relay

JSON Parameters

The parameters for update a Network DHCP Relay is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Description
name Network DHCP Relay name
serverIpAddresses Server IP Addresses for the DHCP Relay

Delete a Network DHCP Relay

curl -XDELETE "$serverUrl/api/networks/servers/:serverId/dhcp-relays/:id`
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network DHCP Relay from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/servers/:serverId/dhcp-relays/:id

URL Parameters

Parameter Description
serverId ID of the network server
id The ID of the Network DHCP Relay

Network Edge Clusters

Provides API interfaces for managing Network Edge Clusters for a Network Service within Morpheus.

Get all Network Edge Clusters for Network Server

curl "$serverUrl/api/networks/servers/1/edge-clusters" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "networkEdgeClusters": [
        {
            "id": 1,
            "internalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "visibility": "public",
            "dateCreated": "2021-11-01T23:02:22Z",
            "providerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "lastUpdated": "2021-11-04T21:23:59Z",
            "active": true,
            "displayName": "test-edge-cluster",
            "name": "test-edge-cluster",
            "enabled": true,
            "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "config": {
                "clusterProfileBindings": "nsx-default-edge-high-availability-profile",
                "members": 2,
                "deploymentType": "VIRTUAL_MACHINE",
                "memberNodeType": "EDGE_NODE"
            },
            "owner": {
                "id": 1
            },
            "networkServer": {
                "id": 3
            },
            "zone": {
                "id": 5
            },
            "tenants": [
                {
                    "id": 1,
                    "name": "Stubby Toes Inc."
                }
            ]
        }
    ],
    "meta": {
        "max": "25",
        "offset": "0",
        "sort": "name",
        "order": "asc",
        "total": 1
    }
}

This endpoint retrieves all Network Edge Clusters for a specified Network Service.

HTTP Request

GET $serverUrl/api/networks/servers/:id/edge-clusters

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load network Edge Clusters that contain the phrase specified in name or description

Get a Specific Network Edge Cluster

curl "$serverUrl/api/networks/servers/1/edge-clusters/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "networkEdgeCluster": {
        "id": 1,
        "internalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "visibility": "public",
        "dateCreated": "2021-11-01T23:02:22Z",
        "providerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "lastUpdated": "2021-11-04T21:23:38Z",
        "active": true,
        "displayName": "test-edge-cluster-rename",
        "name": "test-edge-cluster-rename",
        "enabled": true,
        "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "config": {
            "clusterProfileBindings": "nsx-default-edge-high-availability-profile",
            "members": 2,
            "deploymentType": "VIRTUAL_MACHINE",
            "memberNodeType": "EDGE_NODE"
        },
        "owner": {
            "id": 1
        },
        "networkServer": {
            "id": 3
        },
        "zone": {
            "id": 5
        },
        "tenants": [
            {
                "id": 1,
                "name": "Stubby Toes Inc."
            }
        ]
    }
}

This endpoint retrieves a specific network Edge Cluster.

HTTP Request

GET $serverUrl/api/networks/servers/:serverId/edge-clusters/:edgeClusterId

URL Parameters

Parameter Description
serverId ID of the network server
edgeClusterId ID of the network Edge Cluster

Update a Network Edge Cluster

Use this command to update an existing network Edge Cluster.

curl -XPUT "$serverUrl/api/networks/servers/1/edge-clusters/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
        "networkEdgeCluster": {
          "name": "stubby-toes-edge-cluster",
          "description": null,
          "visibility": "public",
          "tenants": [
            {
              "id": 1
            },
            {
              "id": 2
            }
          ]
        }
    }'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/servers/:serverId/edge-clusters/:edgeClusterId

URL Parameters

Parameter Description
serverId ID of the network server
edgeClusterId ID of the network Edge Cluster

JSON Parameters

The parameters for update a network Edge Cluster is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Description
name Network Edge Cluster name
description Network Edge Cluster description
visibility private or public
tenants Array of tenant account ids that are allowed access

Network Types

Provides API for viewing Network Types and their configuration options.

curl "$serverUrl/api/network-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkTypes": [
    {
      "id": 8,
      "code": "azureNetwork",
      "name": "Network",
      "description": "",
      "category": "azure",
      "externalType": null,
      "creatable": true,
      "overlay": false,
      "nameEditable": false,
      "cidrEditable": false,
      "dhcpServerEditable": false,
      "dnsEditable": false,
      "gatewayEditable": false,
      "vlanIdEditable": false,
      "canAssignPool": false,
      "deletable": true,
      "optionTypes": [
        {
          "id": 1139,
          "name": "resourceGroup",
          "code": "network.azure.resourceGroup",
          "description": null,
          "fieldName": "resourceGroupId",
          "fieldLabel": "Resource Group",
          "fieldContext": "config",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "placeHolder": null,
          "helpBlock": "",
          "defaultValue": null,
          "optionSource": "azureZonePools",
          "type": "select",
          "advanced": false,
          "required": true,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 1,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        },
        {
          "id": 1140,
          "name": "subnetName",
          "code": "network.azure.subnetName",
          "description": null,
          "fieldName": "subnetName",
          "fieldLabel": "Subnet Name",
          "fieldContext": "config",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "placeHolder": null,
          "helpBlock": "",
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": true,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 3,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        },
        {
          "id": 1138,
          "name": "addressSpace",
          "code": "network.azure.addressSpace",
          "description": null,
          "fieldName": "addressSpace",
          "fieldLabel": "Address Space",
          "fieldContext": "config",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "placeHolder": null,
          "helpBlock": "The virtual networks's address range in CIDR notation",
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": true,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 2,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        },
        {
          "id": 1141,
          "name": "subnetCidr",
          "code": "network.azure.subnet.cidr",
          "description": null,
          "fieldName": "subnetCidr",
          "fieldLabel": "Subnet Cidr",
          "fieldContext": "config",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "placeHolder": null,
          "helpBlock": "The subnet's address range in CIDR notation (e.g. 192.168.1.0/24). It must be contained by the address space of the virtual network.",
          "defaultValue": null,
          "optionSource": null,
          "type": "text",
          "advanced": false,
          "required": true,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 4,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        }
      ]
    },
    {
      "id": 50,
      "code": "azureSubnet",
      "name": "Subnet",
      "description": "",
      "category": null,
      "externalType": null,
      "creatable": false,
      "overlay": false,
      "nameEditable": false,
      "cidrEditable": false,
      "dhcpServerEditable": false,
      "dnsEditable": false,
      "gatewayEditable": false,
      "vlanIdEditable": false,
      "canAssignPool": false,
      "deletable": false,
      "optionTypes": [

      ]
    }
  ],
  "meta": {
    "size": 25,
    "total": 52,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Network Types. The sample response has been abbreviated.

HTTP Request

GET $serverUrl/api/network-types

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
code If specified will return an exact match on code
phrase If specified will return a partial match on name

Get a Specific Network Type

curl "$serverUrl/api/network-types/9" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkType": {
    "id": 9,
    "code": "amazonSubnet",
    "name": "Amazon Subnet",
    "description": "",
    "category": "amazon",
    "externalType": null,
    "creatable": true,
    "overlay": false,
    "nameEditable": false,
    "cidrEditable": false,
    "dhcpServerEditable": false,
    "dnsEditable": false,
    "gatewayEditable": false,
    "vlanIdEditable": false,
    "canAssignPool": false,
    "deletable": true,
    "optionTypes": [
      {
        "id": 1022,
        "name": "availabilityZone",
        "code": "network.amazon.availabilityZone",
        "description": null,
        "fieldName": "availabilityZone",
        "fieldLabel": "Availability Zone",
        "fieldContext": "domain",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "placeHolder": null,
        "helpBlock": "",
        "defaultValue": null,
        "optionSource": "amazonAvailabilityZones",
        "type": "select",
        "advanced": false,
        "required": false,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 32,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "contextualDefault": false
      },
      {
        "id": 1015,
        "name": "assignPublicIp",
        "code": "network.global.assignPublicIp",
        "description": null,
        "fieldName": "assignPublicIp",
        "fieldLabel": "Assign Public",
        "fieldContext": "domain",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "placeHolder": null,
        "helpBlock": "",
        "defaultValue": null,
        "optionSource": null,
        "type": "checkbox",
        "advanced": false,
        "required": false,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 33,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "contextualDefault": false
      },
      {
        "id": 871,
        "name": "cidr",
        "code": "network.global.cidr",
        "description": null,
        "fieldName": "cidr",
        "fieldLabel": "cidr",
        "fieldContext": "domain",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "placeHolder": null,
        "helpBlock": "",
        "defaultValue": null,
        "optionSource": null,
        "type": "text",
        "advanced": false,
        "required": true,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 10,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "contextualDefault": false
      },
      {
        "id": 1014,
        "name": "zonePool",
        "code": "network.global.zonePool",
        "description": null,
        "fieldName": "zonePool.id",
        "fieldLabel": "VPC",
        "fieldContext": "domain",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "placeHolder": null,
        "helpBlock": "",
        "defaultValue": null,
        "optionSource": "zonePoolsId",
        "type": "select",
        "advanced": false,
        "required": true,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 31,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "contextualDefault": false
      }
    ]
  }
}

This endpoint retrieves a specific Network Type.

HTTP Request

GET $serverUrl/api/network-types/:id

URL Parameters

Parameter Description
ID The ID of the Network Type to retrieve

Network Firewalls

Provides API interfaces for managing Network Firewalls for a Network Service within Morpheus.

Get all Network Firewall Rules for Network Server

curl "$serverUrl/api/networks/servers/1/firewall-rules" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "rules": [
    {
      "id": 1,
      "direction": "ingress",
      "sourceType": "cidr",
      "destinationType": "instance",
      "name": "stubby-toes-rule-1",
      "policy": "accept",
      "priority": 0,
      "enabled": true,
      "ruleGroup": {
        "id": 1,
        "name": "stubby-toes-group"
      },
      "groupName": "stubby-toes-group",
      "config": {

      },
      "sources": [
        {
          "id": "/infra/domains/default/groups/DB",
          "name": "DB"
        },
        {
          "id": "/infra/domains/default/groups/stubby-toes-group",
          "name": "stubby-toes-group"
        }
      ],
      "destinations": [
        {
          "id": "/infra/domains/default/groups/stubby-toes-group",
          "name": "stubby-toes-group"
        },
        {
          "id": "/infra/domains/default/groups/DB",
          "name": "DB"
        }
      ],
      "applications": [
        {
          "id": "/infra/services/ICMP-ALL",
          "name": "ICMP-ALL"
        }
      ],
      "scopes": [
        {
          "id": "/infra/domains/default/groups/DB",
          "name": "DB"
        },
        {
          "id": "/infra/domains/default/groups/stubby-toes-group",
          "name": "stubby-toes-group"
        }
      ],
      "profiles": [
        {
          "id": "ANY",
          "name": "ANY"
        }
      ],
      "appliedTargets": [

      ]
    }
  ]
}

This endpoint retrieves all Network Firewall Rules for a specified Network Service.

HTTP Request

GET $serverUrl/api/networks/servers/:id/firewall-rules

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load network firewall rules that contain the phrase specified in name or description

Get a Specific Network Firewall Rule

curl "$serverUrl/api/networks/servers/1/firewall-rules/1" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "rule": {
    "id": 1,
    "direction": "ingress",
    "sourceType": "cidr",
    "destinationType": "instance",
    "name": "stubby-toes-rule-1",
    "policy": "accept",
    "priority": 0,
    "enabled": true,
    "ruleGroup": {
      "id": 1,
      "name": "stubby-toes-group"
    },
    "groupName": "stubby-toes-group",
    "config": {

    },
    "sources": [
      {
        "id": "/infra/domains/default/groups/DB",
        "name": "DB"
      },
      {
        "id": "/infra/domains/default/groups/stubby-toes-group",
        "name": "stubby-toes-group"
      }
    ],
    "destinations": [
      {
        "id": "/infra/domains/default/groups/stubby-toes-group",
        "name": "stubby-toes-group"
      },
      {
        "id": "/infra/domains/default/groups/DB",
        "name": "DB"
      }
    ],
    "applications": [
      {
        "id": "/infra/services/ICMP-ALL",
        "name": "ICMP-ALL"
      }
    ],
    "scopes": [
      {
        "id": "/infra/domains/default/groups/DB",
        "name": "DB"
      },
      {
        "id": "/infra/domains/default/groups/stubby-toes-group",
        "name": "stubby-toes-group"
      }
    ],
    "profiles": [
      {
        "id": "ANY",
        "name": "ANY"
      }
    ],
    "appliedTargets": [

    ]
  }
}

This endpoint retrieves a specific network firewall rule.

HTTP Request

GET $serverUrl/api/networks/servers/:serverId/firewall-rules/:ruleId

URL Parameters

Parameter Description
serverId ID of the network server
ruleId ID of the network firewall rule

Create a Network Firewall Rule

Use this command to create a network firewall rule.

curl -XPOST "$serverUrl/api/networks/servers/1/firewall-rules" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
  "rule": {
    "ruleGroup": {
      "id": 1032
    },
    "name": "stubby-toes-rule",
    "description": null,
    "enabled": true,
    "priority": null,
    "direction": "ingress",
    "sources": {
      "id": [
        "/infra/domains/default/groups/stubby-toes-group"
      ]
    },
    "destinations": {
      "id": [
        "/infra/domains/default/groups/stubby-toes-group"
      ]
    },
    "config": {
      "application": [
        "HTTP"
      ],
      "profile": [
        "HTTP"
      ]
    },
    "scopes": {
      "id": [
        "/infra/domains/default/groups/stubby-toes-group"
      ]
    },
    "policy": "accept"
  }
}'

The above command returns JSON Structured like this:

{
  "id": 1,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/servers/:serverId/firewall-rules

JSON Parameters

The parameters for creating a network firewall rule is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Required Description
ruleGroup.id * Firewall rule group for rule (*applicable to select network servers).
name Y Network firewall rule name
description N Network firewall rule description
priority N Network firewall rule priority
enabled N Use this to set enabled state

Update a Network Firewall Rule

Use this command to update an existing network firewall rule.

curl -XPUT "$serverUrl/api/networks/servers/1/firewall-rules/1" \
-H "Authorization: BEARER $accessToken"
-H "Content-Type: application/json" \
-d '{
  "rule": {
    "name": "name",
    "description": "description",
    "enabled": false,
    "priority": 10
  }
}'

The above command returns JSON structured like this:

{
"success": true
}

HTTP Request

PUT $serverUrl/api/networks/servers/:serverId/firewall-rules/:ruleId

URL Parameters

Parameter Description
serverId ID of the network server
ruleId ID of the network firewall rule

JSON Parameters

The parameters for update a network firewall rule is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Description
name Network firewall rule name
description Network firewall rule description
priority Network firewall rule priority
enabled Use this to set enabled state

Delete a Network firewall rule

curl -XDELETE "$serverUrl/api/networks/servers/1/firewall-rules/1" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
"success": true
}

Will delete a network firewall rule.

HTTP Request

DELETE $serverUrl/api/networks/servers/:serverId/firewall-rules/:ruleId

URL Parameters

Parameter Description
serverId ID of the network server
ruleId ID of the network firewall rule

Get all Network Firewall Rule Groups for Network Server

curl "$serverUrl/api/networks/servers/1/firewall-rule-groups" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "ruleGroups": [
    {
      "id": 1,
      "name": "stubby-toes-group",
      "description": null,
      "priority": 0,
      "groupLayer": "Infrastructure",
      "rules": [
        {
          "id": 1,
          "direction": "ingress",
          "sourceType": "cidr",
          "destinationType": "instance",
          "name": "stubby-toes-rule-1",
          "policy": "accept",
          "priority": 0,
          "enabled": true,
          "ruleGroup": {
            "id": 1,
            "name": "stubby-toes-group"
          },
          "groupName": "stubby-toes-group",
          "config": {

          },
          "sources": [
            {
              "id": "/infra/domains/default/groups/DB",
              "name": "DB"
            },
            {
              "id": "/infra/domains/default/groups/stubby-toes-group",
              "name": "stubby-toes-group"
            }
          ],
          "destinations": [
            {
              "id": "/infra/domains/default/groups/stubby-toes-group",
              "name": "stubby-toes-group"
            },
            {
              "id": "/infra/domains/default/groups/DB",
              "name": "DB"
            }
          ],
          "applications": [
            {
              "id": "/infra/services/ICMP-ALL",
              "name": "ICMP-ALL"
            }
          ],
          "scopes": [
            {
              "id": "/infra/domains/default/groups/DB",
              "name": "DB"
            },
            {
              "id": "/infra/domains/default/groups/stubby-toes-group",
              "name": "stubby-toes-group"
            }
          ],
          "profiles": [
            {
              "id": "ANY",
              "name": "ANY"
            }
          ],
          "appliedTargets": [

          ]
        }
      ]
    }
  ]
}

This endpoint retrieves all Network Firewall Rule Groups for a specified Network Service.

HTTP Request

GET $serverUrl/api/networks/servers/:id/firewall-rule-groups

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Restricts query to only load network firewall rule groups that contain the phrase specified in name or description

Get a Specific Network Firewall Rule Group

curl "$serverUrl/api/networks/servers/1/firewall-rule-groups/1" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "stubby-toes-group",
  "description": null,
  "priority": 0,
  "groupLayer": "Infrastructure",
  "rules": [
    {
      "id": 1,
      "direction": "ingress",
      "sourceType": "cidr",
      "destinationType": "instance",
      "name": "stubby-toes-rule-1",
      "policy": "accept",
      "priority": 0,
      "enabled": true,
      "ruleGroup": {
        "id": 1,
        "name": "stubby-toes-group"
      },
      "groupName": "stubby-toes-group",
      "config": {

      },
      "sources": [
        {
          "id": "/infra/domains/default/groups/DB",
          "name": "DB"
        },
        {
          "id": "/infra/domains/default/groups/stubby-toes-group",
          "name": "stubby-toes-group"
        }
      ],
      "destinations": [
        {
          "id": "/infra/domains/default/groups/stubby-toes-group",
          "name": "stubby-toes-group"
        },
        {
          "id": "/infra/domains/default/groups/DB",
          "name": "DB"
        }
      ],
      "applications": [
        {
          "id": "/infra/services/ICMP-ALL",
          "name": "ICMP-ALL"
        }
      ],
      "scopes": [
        {
          "id": "/infra/domains/default/groups/DB",
          "name": "DB"
        },
        {
          "id": "/infra/domains/default/groups/stubby-toes-group",
          "name": "stubby-toes-group"
        }
      ],
      "profiles": [
        {
          "id": "ANY",
          "name": "ANY"
        }
      ],
      "appliedTargets": [

      ]
    }
  ]
}

This endpoint retrieves a specific network firewall rule group.

HTTP Request

GET $serverUrl/api/networks/servers/:serverId/firewall-rule-groups/:groupId

URL Parameters

Parameter Description
serverId ID of the network server
groupId ID of the network firewall rule group

Create a Network Firewall Rule Group

Use this command to create a network firewall rule group.

curl -XPOST "$serverUrl/api/networks/servers/1/firewall-rule-groups" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
  "ruleGroup": {
    "name": "stubby-toes-group",
    "description": "description",
    "priority": 10,
    "externalType": "SecurityPolicy",
    "groupLayer": "Infrastructure"
  }
}'

The above command returns JSON Structured like this:

{
  "id": 1,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/servers/:serverId/firewall-rule-groups

JSON Parameters

The parameters for creating a network firewall rule group is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Required Description
name Y Network firewall rule group name
description N Network firewall rule group description
priority N Network firewall rule group priority
externalType Y Use SecurityPolicy

Update a Network Firewall Rule Group

Use this command to update an existing network firewall rule group.

curl -XPUT "$serverUrl/api/networks/servers/1/firewall-rule-groups/1" \
-H "Authorization: BEARER $accessToken"
-H "Content-Type: application/json" \
-d '{
  "ruleGroup": {
    "name": "name",
    "description": "description",
    "priority": 10
  }
}'

The above command returns JSON structured like this:

{
"success": true
}

HTTP Request

PUT $serverUrl/api/networks/servers/:serverId/firewall-rule-groups/:groupId

URL Parameters

Parameter Description
serverId ID of the network server
groupId ID of the network firewall rule group

JSON Parameters

The parameters for update a network firewall rule group is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Description
name Network firewall rule group name
description Network firewall rule group description
priority Network firewall rule group priority

Delete a Network firewall rule group

curl -XDELETE "$serverUrl/api/networks/servers/1/firewall-rule-groups/1" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
"success": true
}

Will delete a network firewall rule group.

HTTP Request

DELETE $serverUrl/api/networks/servers/:serverId/firewall-rule-groups/:groupId

URL Parameters

Parameter Description
serverId ID of the network server
groupId ID of the network firewall rule group

Network Groups

Provides API for managing Network Groups.

curl "$serverUrl/api/networks/groups"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkGroups": [
    {
      "id": 1,
      "name": "test network group",
      "description": "a test network group",
      "visibility": "private",
      "active": true,
      "networks": [
        1
      ],
      "subnets": [

      ],
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Network Groups associated with the account.

HTTP Request

GET $serverUrl/api/networks/groups

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Network Group

curl "$serverUrl/api/networks/groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkGroup": {
    "id": 1,
    "name": "test network group",
    "description": "a test network group",
    "visibility": "private",
    "active": true,
    "networks": [
      1
    ],
    "subnets": [

    ],
    "tenants": [
      {
        "id": 1,
        "name": "root"
      }
    ],
    "resourcePermission": {
      "all": true,
      "sites": [
        {
          "id": 284,
          "name": "anothergroup",
          "default": true
        },
        {
          "id": 317,
          "name": "another group",
          "default": false
        }
      ],
      "allPlans": null,
      "plans": [

      ]
    }
  },
  "networks": [
    {
      "id": 1,
      "name": "VM Network",
      "zone": {
        "id": 29,
        "name": "den-vcenter"
      },
      "type": {
        "id": 6,
        "name": "VMWare Network",
        "code": "vmwareNetwork"
      },
      "owner": {
        "id": 1,
        "name": "root"
      },
      "code": "vmware.network.29.network-51",
      "category": "vmware.network.29",
      "interfaceName": null,
      "bridgeName": null,
      "bridgeInterface": null,
      "description": "VM Network",
      "externalId": "network-51",
      "internalId": null,
      "uniqueId": "network-51",
      "externalType": "Network",
      "refUrl": null,
      "refType": "ComputeZone",
      "refId": 29,
      "vlanId": null,
      "vswitchName": null,
      "dhcpServer": true,
      "dhcpIp": null,
      "gateway": null,
      "netmask": null,
      "broadcast": null,
      "subnetAddress": null,
      "dnsPrimary": null,
      "dnsSecondary": null,
      "cidr": null,
      "tftpServer": null,
      "bootFile": null,
      "switchId": null,
      "fabricId": null,
      "networkRole": null,
      "status": null,
      "availabilityZone": null,
      "pool": null,
      "networkProxy": null,
      "networkDomain": null,
      "prefixLength": null,
      "visibility": "private",
      "enableAdmin": false,
      "scanNetwork": null,
      "active": true,
      "defaultNetwork": false,
      "assignPublicIp": false,
      "noProxy": null,
      "applianceUrlProxyBypass": true,
      "zonePool": {
        "id": 12,
        "name": "labs-den-pool"
      },
      "allowStaticOverride": null,
      "subnets": [

      ]
    }
  ],
  "subnets": [

  ]
}

This endpoint retrieves a specific Network Group.

HTTP Request

GET $serverUrl/api/networks/groups/:id

URL Parameters

Parameter Description
ID The ID of the Network Group to retrieve

Create a Network Group

curl -XPOST "$serverUrl/api/networks/groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkGroup": {
    "name": "test network group",
    "description": "a test network group",
    "networks": [
      1
    ],
    "subnets": [

    ]
  }
}'

The above command returns JSON structured like getting a single Network Group:

HTTP Request

POST $serverUrl/api/networks/groups

JSON Parameters

Parameter Default Description
name Name
description Description

Update a Network Group

curl -XPUT "$serverUrl/api/networks/groups/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkGroup": {
    "name": "my network group",
    "description": "my test network group",
    "networks": [
      2
    ],
    "subnets": [

    ]
  }
}'

The above command returns JSON structured like getting a single Network Group:

HTTP Request

PUT $serverUrl/api/networks/groups/:id

URL Parameters

Parameter Description
ID The ID of the Network Group

JSON Parameters

Same as Create.

Delete a Network Group

curl -XDELETE "$serverUrl/api/networks/groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network Group from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/groups/:id

URL Parameters

Parameter Description
ID The ID of the Network Group

Subnets

Provides API for managing Network Subnets.

curl "$serverUrl/api/subnets"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:


{
  "subnets": [
    {
      "id": 26,
      "code": null,
      "name": "test-subnet",
      "active": true,
      "description": null,
      "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-aa3021a798/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/test-subnets",
      "uniqueId": null,
      "addressPrefix": null,
      "cidr": "192.168.1.0/24",
      "gateway": null,
      "netmask": "255.255.255.0",
      "subnetAddress": "192.168.1.0/24",
      "tftpServer": null,
      "bootFile": null,
      "pool": null,
      "dhcpServer": true,
      "hasFloatingIps": false,
      "dhcpIp": null,
      "dnsPrimary": null,
      "dnsSecondary": null,
      "dhcpStart": "192.168.1.1",
      "dhcpEnd": "192.168.1.254",
      "dhcpRange": null,
      "networkProxy": null,
      "networkDomain": null,
      "searchDomains": null,
      "defaultNetwork": false,
      "assignPublicIp": false,
      "visibility": "private",
      "status": {
        "name": "AVAILABLE"
      },
      "network": {
        "id": 55,
        "name": "our-subnet"
      },
      "type": {
        "id": 6,
        "code": "azure",
        "name": "Azure Subnet"
      },
      "account": {
        "id": 1,
        "name": "root"
      },
      "securityGroups": [

      ],
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ],
      "resourcePermission": {
        "all": true,
        "sites": [

        ],
        "allPlans": true,
        "plans": [

        ]
      }
    },
    {
      "id": 77,
      "code": null,
      "name": "test-subnet2",
      "active": true,
      "description": null,
      "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-aa3021a798/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/test-subnets2",
      "uniqueId": null,
      "addressPrefix": null,
      "cidr": "192.168.2.0/24",
      "gateway": null,
      "netmask": "255.255.255.0",
      "subnetAddress": "192.168.2.0/24",
      "tftpServer": null,
      "bootFile": null,
      "pool": null,
      "dhcpServer": true,
      "hasFloatingIps": false,
      "dhcpIp": null,
      "dnsPrimary": null,
      "dnsSecondary": null,
      "dhcpStart": "192.168.2.1",
      "dhcpEnd": "192.168.2.254",
      "dhcpRange": null,
      "networkProxy": null,
      "networkDomain": null,
      "searchDomains": null,
      "defaultNetwork": false,
      "assignPublicIp": false,
      "visibility": "private",
      "status": {
        "name": "AVAILABLE"
      },
      "network": {
        "id": 55,
        "name": "our-subnet"
      },
      "type": {
        "id": 6,
        "code": "azure",
        "name": "Azure Subnet"
      },
      "account": {
        "id": 1,
        "name": "root"
      },
      "securityGroups": [

      ],
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ],
      "resourcePermission": {
        "all": true,
        "sites": [

        ],
        "allPlans": true,
        "plans": [

        ]
      }
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Subnets associated with the account.

HTTP Request

GET $serverUrl/api/subnets

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get Subnets for a Network

curl "$serverUrl/api/networks/55/subnets"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:


{
  "subnets": [
    {
      "id": 26,
      "code": null,
      "name": "test-subnet",
      "active": true,
      "description": null,
      "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-aa3021a798/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/test-subnets",
      "uniqueId": null,
      "addressPrefix": null,
      "cidr": "192.168.1.0/24",
      "gateway": null,
      "netmask": "255.255.255.0",
      "subnetAddress": "192.168.1.0/24",
      "tftpServer": null,
      "bootFile": null,
      "pool": null,
      "dhcpServer": true,
      "hasFloatingIps": false,
      "dhcpIp": null,
      "dnsPrimary": null,
      "dnsSecondary": null,
      "dhcpStart": "192.168.1.1",
      "dhcpEnd": "192.168.1.254",
      "dhcpRange": null,
      "networkProxy": null,
      "networkDomain": null,
      "searchDomains": null,
      "defaultNetwork": false,
      "assignPublicIp": false,
      "visibility": "private",
      "status": {
        "name": "AVAILABLE"
      },
      "network": {
        "id": 55,
        "name": "our-subnet"
      },
      "type": {
        "id": 6,
        "code": "azure",
        "name": "Azure Subnet"
      },
      "account": {
        "id": 1,
        "name": "root"
      },
      "securityGroups": [

      ],
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ],
      "resourcePermission": {
        "all": true,
        "sites": [

        ],
        "allPlans": true,
        "plans": [

        ]
      }
    },
    {
      "id": 77,
      "code": null,
      "name": "test-subnet2",
      "active": true,
      "description": null,
      "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-aa3021a798/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/test-subnets2",
      "uniqueId": null,
      "addressPrefix": null,
      "cidr": "192.168.2.0/24",
      "gateway": null,
      "netmask": "255.255.255.0",
      "subnetAddress": "192.168.2.0/24",
      "tftpServer": null,
      "bootFile": null,
      "pool": null,
      "dhcpServer": true,
      "hasFloatingIps": false,
      "dhcpIp": null,
      "dnsPrimary": null,
      "dnsSecondary": null,
      "dhcpStart": "192.168.2.1",
      "dhcpEnd": "192.168.2.254",
      "dhcpRange": null,
      "networkProxy": null,
      "networkDomain": null,
      "searchDomains": null,
      "defaultNetwork": false,
      "assignPublicIp": false,
      "visibility": "private",
      "status": {
        "name": "AVAILABLE"
      },
      "network": {
        "id": 55,
        "name": "our-subnet"
      },
      "type": {
        "id": 6,
        "code": "azure",
        "name": "Azure Subnet"
      },
      "account": {
        "id": 1,
        "name": "root"
      },
      "securityGroups": [

      ],
      "tenants": [
        {
          "id": 1,
          "name": "root"
        }
      ],
      "resourcePermission": {
        "all": true,
        "sites": [

        ],
        "allPlans": true,
        "plans": [

        ]
      }
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Subnets under a specific network.

HTTP Request

GET $serverUrl/api/networks/:networkId/subnets

URL Parameters

Parameter Description
:networkId The ID of the Network.

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Subnet

curl "$serverUrl/api/subnets/77" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "subnet": {
    "id": 77,
    "code": null,
    "name": "def2",
    "active": true,
    "description": null,
    "externalId": "/subscriptions/88213e1e-d4c5-467f-b029-aa3021a798/resourceGroups/ARMUbuntu16/providers/Microsoft.Network/virtualNetworks/test-subnets2",
    "uniqueId": null,
    "addressPrefix": null,
    "cidr": "192.168.2.0/24",
    "gateway": null,
    "netmask": "255.255.255.0",
    "subnetAddress": "192.168.2.0/24",
    "tftpServer": null,
    "bootFile": null,
    "pool": null,
    "dhcpServer": true,
    "hasFloatingIps": false,
    "dhcpIp": null,
    "dnsPrimary": null,
    "dnsSecondary": null,
    "dhcpStart": "192.168.2.1",
    "dhcpEnd": "192.168.2.254",
    "dhcpRange": null,
    "networkProxy": null,
    "networkDomain": null,
    "searchDomains": null,
    "defaultNetwork": false,
    "assignPublicIp": false,
    "visibility": "private",
    "status": {
      "name": "AVAILABLE"
    },
    "network": {
      "id": 55,
      "name": "our-subnet"
    },
    "type": {
      "id": 6,
      "code": "azure",
      "name": "Azure Subnet"
    },
    "account": {
      "id": 1,
      "name": "root"
    },
    "securityGroups": [

    ],
    "tenants": [
      {
        "id": 1,
        "name": "root"
      }
    ],
    "resourcePermission": {
      "all": true,
      "sites": [

      ],
      "allPlans": true,
      "plans": [

      ]
    }
  }
}

This endpoint retrieves a specific Subnet.

HTTP Request

GET $serverUrl/api/subnets/:id

URL Parameters

Parameter Description
ID The ID of the Subnet to retrieve

Create a Subnet

curl -XPOST "$serverUrl/api/1/subnets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "subnet": {
    "type": {
      "id": 6
    },
    "config": {
      "subnetName": "My Subnet",
      "subnetCidr": "192.168.2.0/24"
    }
  },
  "resourcePermissions": {
    "all": true
  }
}'

The above command returns JSON structured like getting a single Subnet:

HTTP Request

POST $serverUrl/api/:networkId/subnets

URL Parameters

Parameter Description
:networkId The ID of the Network this subnet will belong to.

JSON Parameters

Parameter Default Description
type.id Subnet Types ID
config Configuration object. Settings vary by type.
visibility private private or public
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

This endpoint allows creating a Subnet. Only certain types of clouds support creating and deleting subnets. Configuration options vary for each Subnet Type.

Update a Subnet

curl -XPUT "$serverUrl/api/subnets/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "subnet": {
    "config": {
      "subnetName": "Our Subnet"
    }
  }
}'

The above command returns JSON structured like getting a single Subnet:

HTTP Request

PUT $serverUrl/api/subnets/:id

URL Parameters

Parameter Description
ID The ID of the Subnet

JSON Parameters

Parameter Default Description
type.id Subnet Types ID
config Configuration object. Settings vary by type.
visibility private private or public
tenantPermissions.accounts Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

This endpoint allows updating a Subnet. Only certain types of clouds support this action. Configuration options vary for each Subnet Type.

Delete a Subnet

curl -XDELETE "$serverUrl/api/subnets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Subnet from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/subnets/:id

URL Parameters

Parameter Description
ID The ID of the Subnet

Network Pools

Provides API for managing Network Pools.

Get All Network Pools

curl "$serverUrl/api/networks/pools"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkPools": [
    {
      "id": 9,
      "type": {
        "id": 2,
        "name": "Morpheus",
        "code": "morpheus"
      },
      "account": {
        "id": 1,
        "name": "root"
      },
      "category": null,
      "code": null,
      "name": "test pool",
      "displayName": null,
      "internalId": null,
      "externalId": null,
      "dnsDomain": null,
      "dnsSearchPath": null,
      "hostPrefix": null,
      "httpProxy": null,
      "dnsServers": [

      ],
      "dnsSuffixList": [

      ],
      "dhcpServer": false,
      "dhcpIp": null,
      "gateway": null,
      "netmask": null,
      "subnetAddress": null,
      "ipCount": 41,
      "freeCount": 41,
      "poolEnabled": true,
      "tftpServer": null,
      "bootFile": null,
      "refType": null,
      "refId": null,
      "parentType": null,
      "parentId": null,
      "poolGroup": null,
      "ipRanges": [
        {
          "id": 8,
          "startAddress": "192.168.15.10",
          "endAddress": "192.168.15.50",
          "internalId": null,
          "externalId": null,
          "description": null,
          "addressCount": 0,
          "active": true,
          "dateCreated": "2017-11-29T04:47:33Z",
          "lastUpdated": "2017-11-29T04:47:33Z"
        }
      ]
    }
  ],
  "networkPoolCount": 1,
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Network Pools associated with the account.

HTTP Request

GET $serverUrl/api/networks/pools

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Network Pool

curl "$serverUrl/api/networks/pools/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkPool": {
    "id": 9,
    "type": {
      "id": 2,
      "name": "Morpheus",
      "code": "morpheus"
    },
    "account": {
      "id": 1,
      "name": "root"
    },
    "category": null,
    "code": null,
    "name": "test pool",
    "displayName": null,
    "internalId": null,
    "externalId": null,
    "dnsDomain": null,
    "dnsSearchPath": null,
    "hostPrefix": null,
    "httpProxy": null,
    "dnsServers": [

    ],
    "dnsSuffixList": [

    ],
    "dhcpServer": false,
    "dhcpIp": null,
    "gateway": null,
    "netmask": null,
    "subnetAddress": null,
    "ipCount": 41,
    "freeCount": 41,
    "poolEnabled": true,
    "tftpServer": null,
    "bootFile": null,
    "refType": null,
    "refId": null,
    "parentType": null,
    "parentId": null,
    "poolGroup": null,
    "ipRanges": [
      {
        "id": 8,
        "startAddress": "192.168.15.10",
        "endAddress": "192.168.15.50",
        "internalId": null,
        "externalId": null,
        "description": null,
        "addressCount": 0,
        "active": true,
        "dateCreated": "2017-11-29T04:47:33Z",
        "lastUpdated": "2017-11-29T04:47:33Z"
      }
    ]
  }
}

This endpoint retrieves a specific Network Pool.

HTTP Request

GET $serverUrl/api/networks/pools/:id

URL Parameters

Parameter Description
ID The ID of the Network Pool to retrieve

Create a Network Pool

curl -XPOST "$serverUrl/api/networks/pools" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkPool": {
    "name": "test pool",
    "type": {
      "code": "morpheus"
    },
    "ipRanges": [
      {
        "startAddress": "192.2.2.100",
        "endAddress": "192.2.2.199",
      }
    ]
  }
}'

The above command returns JSON structured like getting a single Network Pool:

HTTP Request

POST $serverUrl/api/networks/pools

JSON Parameters

Parameter Default Description
name Name
type Pool Type. i.e. ‘morpheus’, 'phpipam’, etc.
ipRanges N Array of IP range objects, see IP Ranges, this can only be specified when type is 'morpheus’.
config N Configuration object with parameters that vary by pool type.

IP Ranges

The ipRanges parameter is array of IP range objects with following fields:

Parameter Required Description
startAddress Y Starting IP Address
endAddress Y Ending IP Address

Update a Network Pool

curl -XPUT "$serverUrl/api/networks/pools/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkPool": {
    "name": "test ip pool"
  }
}'

The above command returns JSON structured like getting a single Network Pool:

HTTP Request

PUT $serverUrl/api/networks/pools/:id

URL Parameters

Parameter Description
ID The ID of the Network Pool

JSON Parameters

Same as Create.

Delete a Network Pool

curl -XDELETE "$serverUrl/api/networks/pools/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network Pool from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/pools/:id

URL Parameters

Parameter Description
ID The ID of the Network Pool

Network Domains

Provides API for managing Network Domains.

Get All Network Domains

curl "$serverUrl/api/networks/domains"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkDomains": [
    {
      "id": 2,
      "name": "mydomain.local",
      "active": true,
      "fqdn": null,
      "description": null,
      "visibility": "private",
      "domainController": false,
      "publicZone": false,
      "domainUsername": null,
      "domainPassword": null,
      "refType": null,
      "refId": null,
      "refSource": null,
      "internalId": null,
      "ouPath": null,
      "dcServer": null,
      "zoneType": null,
      "dnssec": null,
      "domainSerial": null,
      "account": {
        "id": 1,
        "name": "root"
      },
      "owner": {
        "id": 1,
        "name": "root"
      }
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Network Domains associated with the account.

HTTP Request

GET $serverUrl/api/networks/domains

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Network Domain

curl "$serverUrl/api/networks/domains/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkDomain": {
    "id": 1,
    "name": "testdomain.xyz",
    "active": true,
    "fqdn": "testdomain.xyz.",
    "description": "an example domain",
    "visibility": "private",
    "domainController": false,
    "publicZone": false,
    "domainUsername": null,
    "domainPassword": null,
    "refType": "AccountIntegration",
    "refId": 18,
    "refSource": "integration",
    "internalId": null,
    "ouPath": null,
    "dcServer": null,
    "zoneType": "Authoritative",
    "dnssec": null,
    "domainSerial": null,
    "account": {
      "id": 1,
      "name": "root"
    },
    "owner": {
      "id": 1,
      "name": "root"
    }
  }
}

This endpoint retrieves a specific Network Domain.

HTTP Request

GET $serverUrl/api/networks/domains/:id

URL Parameters

Parameter Description
ID The ID of the Network Domain to retrieve

Create a Network Domain

curl -XPOST "$serverUrl/api/networks/domains" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkDomain": {
    "name": "test.xyz",
    "description": "A test domain"
  }
}'

The above command returns JSON structured like getting a single Network Domain:

HTTP Request

POST $serverUrl/api/networks/domains

JSON Parameters

Parameter Default Description
name Name
description Description
displayName Overrides displayed name in domain selection components. Useful if using many OU Paths.
publicZone false Public Zone
taskSetId Workflow ID. Workflows can be applied to an instance when associated with a domain. Useful for custom domain related scripting. (Important if wanting to ensure the computer is removed from the domain using teardown phased workflows.)
active true Active
domainController true Join Domain Controller
domainUsername true Domain Username
domainPassword true Domain Password
dcServer DC Server. If specified, must be the server name and not an IP Address.
ouPath OU Path. (i.e. ‘OU=staging,DC=ad,DC=yourdomain,DC=com’)
guestUsername Guest Username. If set, will change the instances RPC Service User after joining a Domain.
guestPassword Guest Password

Update a Network Domain

curl -XPUT "$serverUrl/api/networks/domains/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkDomain": {
    "description": "an excellent domain"
  }
}'

The above command returns JSON structured like getting a single Network Domain:

HTTP Request

PUT $serverUrl/api/networks/domains/:id

URL Parameters

Parameter Description
ID The ID of the Network Domain

JSON Parameters

Same as Create.

Delete a Network Domain

curl -XDELETE "$serverUrl/api/networks/domains/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network Domain from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/domains/:id

URL Parameters

Parameter Description
ID The ID of the Network Domain

Network Proxies

Provides API for managing Network Proxies.

Get All Network Proxies

curl "$serverUrl/api/networks/proxies"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkProxies": [
    {
      "id": 1,
      "name": "myproxy",
      "proxyHost": "10.30.50.100",
      "proxyPort": 9091,
      "proxyUser": null,
      "proxyPassword": null,
      "proxyDomain": "myproxy.com",
      "proxyWorkstation": null,
      "visibility": "private",
      "account": {
        "id": 1,
        "name": "root"
      },
      "owner": {
        "id": 1,
        "name": "root"
      }
    }
  ],
  "networkProxyCount": 1,
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all Network Proxies associated with the account.

HTTP Request

GET $serverUrl/api/networks/proxies

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Network Proxy

curl "$serverUrl/api/networks/proxies/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkProxy": {
    "id": 1,
    "name": "myproxy",
    "proxyHost": "10.30.50.100",
    "proxyPort": 9091,
    "proxyUser": null,
    "proxyPassword": null,
    "proxyDomain": "myproxy.com",
    "proxyWorkstation": null,
    "visibility": "private",
    "account": {
      "id": 1,
      "name": "root"
    },
    "owner": {
      "id": 1,
      "name": "root"
    }
  }
}

This endpoint retrieves a specific Network Proxy.

HTTP Request

GET $serverUrl/api/networks/proxies/:id

URL Parameters

Parameter Description
ID The ID of the Network Proxy to retrieve

Create a Network Proxy

curl -XPOST "$serverUrl/api/networks/proxies" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkProxy": {
    "name": "myproxy",
    "proxyHost": "192.168.1.155",
    "proxyPort": "9005",
    "proxyUser": "proxyuser",
    "proxyPassword": "proxypass",
    "visibility": "private"
  }
}'

The above command returns JSON structured like getting a single Network Proxy:

HTTP Request

POST $serverUrl/api/networks/proxies

JSON Parameters

Parameter Default Description
name Name
proxyHost Proxy Host
proxyPort Proxy Port
proxyUser Proxy Username
proxyPassword Proxy Password
proxyDomain Proxy Domain
proxyWorkstation Proxy Workstation
visibility private Visibility
account.id Tenant Account ID

Update a Network Proxy

curl -XPUT "$serverUrl/api/networks/proxies/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "networkProxy": {
    "name": "ourproxy"
  }
}'

The above command returns JSON structured like getting a single Network Proxy:

HTTP Request

PUT $serverUrl/api/networks/proxies/:id

URL Parameters

Parameter Description
ID The ID of the Network Proxy

JSON Parameters

Same as Create.

Delete a Network Proxy

curl -XDELETE "$serverUrl/api/networks/proxies/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Network Proxy from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/networks/proxies/:id

URL Parameters

Parameter Description
ID The ID of the Network Proxy

Network Routers

Provides API interfaces for managing network routers within Morpheus.

Get all Network Routers

curl "$serverUrl/api/networks/routers" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouters": [
    {
      "id": 32,
      "code": "openstack.router.10.93126dd8-023b-44f5-8100-be2980439419",
      "name": "dand-0218",
      "description": null,
      "category": "openstack.router.10",
      "dateCreated": "2020-02-19T03:08:34+0000",
      "lastUpdated": "2020-02-19T04:13:47+0000",
      "routerType": "neutron",
      "status": "ok",
      "enabled": true,
      "externalIp": null,
      "externalId": "93126dd8-023b-44f5-8100-be2980439419",
      "providerId": null,
      "type": {
        "id": 3,
        "code": "huaweiNeutronRouter",
        "name": "Huawei Router",
        "description": "Neutron Router",
        "enabled": true,
        "creatable": true,
        "selectable": true,
        "hasFirewall": false,
        "hasDhcp": false,
        "hasRouting": false,
        "hasNetworkServer": false,
        "optionTypes": [
        ],
        "ruleOptionTypes": [

        ]
      },
      "networkServer": null,
      "zone": {
        "id": 10,
        "code": "huawei",
        "name": "huawei"
      },
      "instance": null,
      "externalNetwork": {
        "id": 76,
        "code": "openstack.network.10.0a2228f2-7f8a-45f1-8e09-9039e1d09975",
        "name": "admin_external_net"
      },
      "site": null,
      "interfaces": [
        {
          "id": 202,
          "name": "93126dd8-023b-44f5-8100-be2980439419",
          "code": null,
          "interfaceType": null,
          "networkPosition": null,
          "ipAddress": "10.1.0.1",
          "cidr": "10.0.0.0/24",
          "externalLink": null,
          "enabled": true,
          "network": {
            "id": 97,
            "name": "1666113f-e399-44a5-8559-20bee838b83a",
            "code": "openstack.network.10.815f77ba-e5fa-410e-b633-17bb620dd99b"
          }
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all network routers.

HTTP Request

GET $serverUrl/api/networks/routers

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load network routers layouts which contain the phrase specified in name or description

Get a Specific Network Router

curl "$serverUrl/api/networks/routers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouter": {
    "id": 99,
    "code": "nsxt.router.13.b05d6532-2742-4dbd-98f2-a62aa8a62ae0",
    "name": "dand-nsxt-t0-0425.1",
    "description": null,
    "category": "nsxt.router.13",
    "dateCreated": "2021-04-25T16:19:27Z",
    "lastUpdated": "2021-07-14T19:12:16Z",
    "routerType": "internal",
    "status": "ok",
    "enabled": true,
    "externalIp": null,
    "externalId": "b05d6532-2742-4dbd-98f2-a62aa8a62ae0",
    "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0",
    "type": {
      "id": 5,
      "code": "nsx-t-tier0-gateway",
      "name": "NSX-T Tier-0 Gateway",
      "description": "NSX-T Tier-0 Gateway",
      "enabled": true,
      "creatable": true,
      "selectable": true,
      "hasFirewall": true,
      "hasDhcp": false,
      "hasRouting": true,
      "hasNat": true,
      "hasNetworkServer": true,
      "hasFirewallGroups": true,
      "hasSecurityGroupPriority": true,
      "optionTypes": [
        {
          "id": 1220,
          "name": "TIER0_IPSEC_LOCAL_IP",
          "description": null,
          "code": "networkRouter.nsxt.edge.tier0.route.redist.TIER0_IPSEC_LOCAL_IP",
          "fieldName": "TIER0_IPSEC_LOCAL_IP",
          "fieldLabel": "IP Sec Local IP",
          "fieldCode": "gomorpheus.label.nsxt.tier0.route.redist.TIER0_IPSEC_LOCAL_IP",
          "fieldContext": "config",
          "fieldGroup": "Route Re-distribution - Tier-0",
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "fieldInput": null,
          "placeHolder": null,
          "verifyPattern": null,
          "helpBlock": null,
          "helpBlockFieldCode": null,
          "defaultValue": null,
          "optionSource": null,
          "optionSourceType": null,
          "optionList": null,
          "type": "checkbox",
          "advanced": false,
          "required": false,
          "exportMeta": false,
          "editable": true,
          "creatable": true,
          "config": {
          },
          "displayOrder": 2030,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "visibleOnCode": null,
          "requireOnCode": null,
          "contextualDefault": false,
          "displayValueOnDetails": null,
          "showOnCreate": true,
          "showOnEdit": true
        }
      ],
      "ruleOptionTypes": [
        {
          "id": 1186,
          "name": "profile",
          "description": null,
          "code": "networkRouter.nsxt.firewall.rule.profiles",
          "fieldName": "profile",
          "fieldLabel": "Profiles",
          "fieldCode": "gomorpheus.label.profiles",
          "fieldContext": "config",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "fieldInput": null,
          "placeHolder": "Any",
          "verifyPattern": null,
          "helpBlock": "",
          "helpBlockFieldCode": null,
          "defaultValue": null,
          "optionSource": "nsxtFirewallRuleProfiles",
          "optionSourceType": null,
          "optionList": null,
          "type": "multiTypeahead",
          "advanced": false,
          "required": false,
          "exportMeta": false,
          "editable": true,
          "creatable": true,
          "config": {
          },
          "displayOrder": 400,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "visibleOnCode": null,
          "requireOnCode": null,
          "contextualDefault": false,
          "displayValueOnDetails": null,
          "showOnCreate": true,
          "showOnEdit": true
        }
      ],
      "firewallGroupOptionTypes": [
        {
          "id": 1548,
          "name": "externalType",
          "description": null,
          "code": "networkRouter.nsxt.firewall.externalType",
          "fieldName": "externalType",
          "fieldLabel": "externalType",
          "fieldCode": null,
          "fieldContext": "group",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "fieldInput": null,
          "placeHolder": null,
          "verifyPattern": null,
          "helpBlock": "",
          "helpBlockFieldCode": null,
          "defaultValue": "GatewayPolicy",
          "optionSource": null,
          "optionSourceType": null,
          "optionList": null,
          "type": "hidden",
          "advanced": false,
          "required": true,
          "exportMeta": false,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 0,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "visibleOnCode": null,
          "requireOnCode": null,
          "contextualDefault": false,
          "displayValueOnDetails": false,
          "showOnCreate": true,
          "showOnEdit": true
        }
      ],
      "natOptionTypes": [
        {
          "id": 1038,
          "name": "description",
          "description": null,
          "code": "networkRouter.global.description",
          "fieldName": "description",
          "fieldLabel": "Description",
          "fieldCode": "gomorpheus.optiontype.Description",
          "fieldContext": "nat",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "fieldInput": null,
          "placeHolder": null,
          "verifyPattern": null,
          "helpBlock": "",
          "helpBlockFieldCode": null,
          "defaultValue": null,
          "optionSource": null,
          "optionSourceType": null,
          "optionList": null,
          "type": "text",
          "advanced": false,
          "required": false,
          "exportMeta": false,
          "editable": true,
          "creatable": true,
          "config": {
          },
          "displayOrder": 10,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "visibleOnCode": null,
          "requireOnCode": null,
          "contextualDefault": false,
          "displayValueOnDetails": null,
          "showOnCreate": null,
          "showOnEdit": null
        }
      ]
    },
    "networkServer": {
      "id": 13,
      "name": "Labs NSX-T",
      "integration": {
        "id": 14,
        "name": "Labs NSX-T",
        "enabled": true,
        "type": "nsx-t",
        "integrationType": {
          "id": 28,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "url": "https://10.32.23.7",
        "port": "22",
        "username": "admin",
        "password": "************",
        "refType": "NetworkServer",
        "refId": "13",
        "isPlugin": false,
        "config": {
        },
        "status": "error",
        "statusDate": "2021-07-15T11:48:33Z",
        "statusMessage": "nsx-t api not reachable",
        "lastSync": "2021-07-14T19:10:59Z",
        "lastSyncDuration": 108394
      }
    },
    "zone": {
      "id": 20,
      "code": "nsxt",
      "name": "QA VMware NSX-T"
    },
    "instance": null,
    "externalNetwork": null,
    "site": null,
    "interfaces": [

    ],
    "firewall": {
      "enabled": true,
      "version": null,
      "defaultPolicy": null,
      "global": null,
      "ruleGroups": [
        {
          "id": 321,
          "name": "Policy_Default_Infra",
          "description": null,
          "externalId": "Policy_Default_Infra",
          "iacId": null,
          "zone": null,
          "zonePool": null,
          "status": "available",
          "priority": 10,
          "groupLayer": "Default",
          "rules": [
            {
              "id": 1056,
              "name": "dand-nsxt-t0-0425.1",
              "code": null,
              "enabled": true,
              "groupName": "Policy_Default_Infra",
              "direction": "any",
              "ruleType": "custom",
              "policy": "accept",
              "source": [
                "ANY"
              ],
              "sourceType": "cidr",
              "destination": [
                "ANY"
              ],
              "destinationType": "instance",
              "profiles": [
                "ANY"
              ],
              "protocol": null,
              "application": null,
              "applicationType": "port",
              "portRange": null,
              "sourcePortRange": null,
              "sourceGroup": null,
              "sourceTier": null,
              "applications": [
                {
                  "id": 432,
                  "name": "ANY"
                }
              ]
            }
          ]
        }
      ]
    },
    "routes": [

    ],
    "nats": [

    ],
    "permissions": {
      "visibility": "private",
      "tenantPermissions": {
        "accounts": [
          1
        ]
      }
    }
  }
}

This endpoint retrieves a specific network router.

HTTP Request

GET $serverUrl/api/networks/routers/:id

URL Parameters

Parameter Description
id ID of the network router

Create a Network Router

Use this command to create a network router.

curl -XPOST "$serverUrl/api/networks/routers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
          "networkRouter": {
              "type": {
                  "id": 9
              },
              "enabled": true,
              "site": {
                  "id": "shared"
              },
              "networkServer": {
                  "id": 8
              },
              "name": "dand-0217",
              "description": null,
              "hostname": "dand",
              "tenantName": null,
              "sizeId": "compact",
              "datastoreId": "datastore-58601",
              "poolId": 9,
              "folderId": "group-v58681",
              "managementNetwork": {
                  "id": 86
              },
              "managementIp": "172.16.30.10",
              "externalNetwork": null,
              "internalNetwork": null,
              "sshUsername": "stubbytoes",
              "sshPassword": "supersecret"
          }
      }'

The above command returns JSON Structured like this:

{
  "id": 104,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/routers

JSON Parameters

The parameters for creating a network router is type dependent. The following lists the common parameters. See get a specific type to list available options for that network router type.

Parameter Required Description
name Y Network router name
type.id Y Network router type ID
site.id Y Group ID or shared
enabled N Can be used to enable / disable the network router (true, false). Default is on
zone.id N Required when type does not support a network server
networkServer.id N Required when type supports a network server

Update a Network Router

Use this command to update an existing network router.

curl -XPUT "$serverUrl/api/networks/routers/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
        "networkRouter": {
            "enabled": true,
            "externalNetwork": {
                "id": 76
            }
            "managementNetwork": {
                "id": 86
            },
            "managementIp": "172.16.30.10",
            "sshPassword": "supersecret"
        }
    }'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/routers/:id

URL Parameters

Parameter Description
id The ID of the network router

JSON Parameters

The parameters for updating a network router is type dependent. The following lists the common parameters. See get a specific type to list available options for that network router type.

Parameter Required Description
enabled N Can be used to enable / disable the network router (true, false). Default is on

Delete a Network Router

curl -XDELETE "$serverUrl/api/networks/routers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a network router.

HTTP Request

DELETE $serverUrl/api/networks/routers/:id

URL Parameters

Parameter Description
id The ID of the network router

Get all Firewall Rules for Network Router

curl "$serverUrl/api/networks/routers/1/firewall-rules" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "rules": [
    {
      "id": 1056,
      "name": "dand-nsxt-t0-0425.1",
      "code": null,
      "enabled": true,
      "priority": 10,
      "groupName": "Policy_Default_Infra",
      "direction": "any",
      "ruleType": "custom",
      "policy": "accept",
      "source": [
        "ANY"
      ],
      "sourceType": "cidr",
      "destination": [
        "ANY"
      ],
      "destinationType": "instance",
      "profiles": [
        "ANY"
      ],
      "protocol": null,
      "application": null,
      "applicationType": "port",
      "portRange": null,
      "sourcePortRange": null,
      "sourceGroup": null,
      "sourceTier": null,
      "applications": [
        {
          "id": 432,
          "name": "ANY"
        }
      ]
    }
  ]
}

This endpoint retrieves all firewall rules for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/firewall-rules

Get a Firewall Rule for Network Router

curl "$serverUrl/api/networks/routers/1/firewall-rules/1056" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "rule": {
    "id": 1056,
    "name": "dand-nsxt-t0-0425.1",
    "code": null,
    "enabled": true,
    "priority": 10,
    "groupName": "Policy_Default_Infra",
    "direction": "any",
    "ruleType": "custom",
    "policy": "accept",
    "source": [
      "ANY"
    ],
    "sourceType": "cidr",
    "destination": [
      "ANY"
    ],
    "destinationType": "instance",
    "profiles": [
      "ANY"
    ],
    "protocol": null,
    "application": null,
    "applicationType": "port",
    "portRange": null,
    "sourcePortRange": null,
    "sourceGroup": null,
    "sourceTier": null,
    "applications": [
      {
        "id": 432,
        "name": "ANY"
      }
    ]
  }
}

This endpoint retrieves a firewall rule.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/firewall-rules/:rule_id

URL Parameters

Parameter Description
router_id The ID of the network router
rule_id The ID of the firewall rule

Create a Network Router Firewall Rule

Use this command to create a firewall rule for an existing network router.

curl -XPOST "$serverUrl/api/networks/routers/1/firewall-rules" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
          "rule": {
              "name": "stubbytoes-rule",
              "config": {
                  "source": null,
                  "destination": null,
                  "application": [
                      "TELNET"
                  ],
                  "profile": null
              },
              "enabled": true,
              "priority": 10,
              "direction": "egress",
              "policy": "accept"
            }
      }'

The above command returns JSON Structured like this:

{
  "id": 800,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/routers/:router_id/firewall-rules

URL Parameters

Parameter Description
router_id The ID of the network router

JSON Parameters

Parameter Required Description
name Y Firewall rule name
enabled N Can be used to enable / disable the rule (true, false). Default is on
priority N Priority for rule

For a full list of available firewall rule options, see ruleOptionTypes in Get a Specific Network Router Type

Update a Network Router Firewall Rule

Use this command to update an existing network router firewall rule.

curl -XPUT "$serverUrl/api/networks/routers/1/firewall-rules" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
        "rule": {
            "enabled": true,
            "priority": 10,
            "name": "New Rule Name"
        }
    }'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/routers/:router_id/firewall-rules/:rule_id

URL Parameters

Parameter Description
router_id The ID of the network router
rule_id The ID of the network router rule

JSON Parameters

The parameters for updating a network router is type dependent. The following lists the common parameters. See get a specific type to list available options for that network router type.

Parameter Required Description
name N Sets name of firewall rule
enabled N Can be used to enable / disable the network router (true, false). Default is on
priority N Sets priority of firewall rule

Delete a Network Router Firewall Rule

curl -XDELETE "$serverUrl/api/networks/routers/1/firewall-rules/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a firewall rule from a network router.

HTTP Request

DELETE $serverUrl/api/networks/routers/:router_id/firewall-rules/:rule_id

URL Parameters

Parameter Description
router_id The ID of the network router
rule_id The ID of the rule to be deleted

Get all Routes for Network Router

curl "$serverUrl/api/networks/routers/1/routes" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRoutes": [
    {
      "id": 58,
      "name": "api-test-route3",
      "code": null,
      "description": null,
      "priority": null,
      "routeType": "static",
      "source": "10.10.0.0/24",
      "sourceType": "cidr",
      "destination": "10.20.0.0",
      "destinationType": "cidr",
      "defaultRoute": false,
      "networkMtu": null,
      "externalInterface": null,
      "internalId": null,
      "externalId": "58ee0c3a-9223-4d01-a1bb-517f48e7b04e",
      "uniqueId": null,
      "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0/static-routes/58ee0c3a-9223-4d01-a1bb-517f48e7b04e",
      "externalType": null,
      "enabled": true,
      "visible": true
    }
  ]
}

This endpoint retrieves all routes for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/routes

URL Parameters

Parameter Description
router_id The ID of the network router

Get a Route for Network Router

curl "$serverUrl/api/networks/routers/1/routes/59" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRoute": {
    "id": 59,
    "name": "api-test-route3",
    "code": "nsxt.router.static.route.13.99.58ee0c3a-9223-4d01-a1bb-517f48e7b04e.10.20.0.0",
    "description": null,
    "priority": null,
    "routeType": "static",
    "source": "10.10.0.0/24",
    "sourceType": "cidr",
    "destination": "10.20.0.0",
    "destinationType": "cidr",
    "defaultRoute": false,
    "networkMtu": null,
    "externalInterface": null,
    "internalId": null,
    "externalId": "58ee0c3a-9223-4d01-a1bb-517f48e7b04e.10.20.0.0",
    "uniqueId": null,
    "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0/static-routes/58ee0c3a-9223-4d01-a1bb-517f48e7b04e",
    "externalType": null,
    "enabled": true,
    "visible": true
  }
}

This endpoint retrieves a network router route for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/routes/:route_id

URL Parameters

Parameter Description
router_id The ID of the network router
route_id The ID of the route

Create a Network Router Route

Use this command to create a route for an existing network router.

curl -XPOST "$serverUrl/api/networks/routers/1/routes" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRoute": {
          "name": "stubbytoes-route",
          "description": "my description",
          "enabled": true,
          "defaultRoute": false,
          "source": "99.99.99.99",
          "destination": "88.88.88.88",
          "networkMtu": "65535"
        }
      }'

The above command returns JSON Structured like this:

{
  "id": 43,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/routers/:router_id/routes

URL Parameters

Parameter Description
router_id The ID of the network router

JSON Parameters

Parameter Required Description
name N Route name
description N Route description
enabled N Can be used to enable / disable the route (true, false). Default is off
defaultRoute N Can be used to set as default route (true, false). Default is off
source Y Source address or range
destination Y Destination address or range
networkMtu Y MTU

Delete a Network Router Route

curl -XDELETE "$serverUrl/api/networks/routers/1/routes/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a route from a network router.

HTTP Request

DELETE $serverUrl/api/networks/routers/:router_id/routes/:route_id

URL Parameters

Parameter Description
router_id The ID of the network router
route_id The ID of the route to be deleted

Update Network Router Permissions

curl -XPUT "$serverUrl/api/networks/routers/1/permissions" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "permissions": {
          "visibility": "public",
          "tenantPermissions": {
            "accounts": [
              1,
              2,
              3
            ]
          }
        }
      }'

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/routers/:id/permissions

URL Parameters

Parameter Description
id The ID of the network router

JSON Parameters

Parameter Required Description
permissions.visibility N Sets visibility: public, private
permissions.tenantPermissions.account N Array of tenant account IDs

Get all Network Router Types

curl "$serverUrl/api/network-router-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouterTypes": [
    {
      "id": 2,
      "code": "opentelekomNeutronRouter",
      "name": "Open Telekom Router",
      "description": "Neutron Router",
      "enabled": true,
      "creatable": true,
      "selectable": true,
      "hasFirewall": false,
      "hasDhcp": false,
      "hasRouting": false,
      "hasNetworkServer": false,
      "optionTypes": [
        {
          "id": 471,
          "name": "networkSubnet",
          "description": null,
          "code": "networkRouter.neutron.internalSubnet",
          "fieldName": "interfaces.networkSubnet.id",
          "fieldLabel": "Internal Subnet",
          "fieldContext": "domain",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "fieldInput": "ipAddress",
          "placeHolder": null,
          "helpBlock": "",
          "defaultValue": null,
          "optionSource": "openstackInternalSubnets",
          "optionList": null,
          "type": "multiSelect",
          "advanced": false,
          "required": true,
          "editable": true,
          "creatable": true,
          "config": {
          },
          "displayOrder": 120,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": "router.zone.id",
          "contextualDefault": false
        }
      ],
      "ruleOptionTypes": [

      ],
      "natOptionTypes": [

      ],
      "ruleGroupOptionTypes": [

      ]
    }
  ]
}

This endpoint retrieves all network router types.

HTTP Request

GET $serverUrl/api/network-router-types

Get a Specific Network Router Type

curl "$serverUrl/api/network-router-types/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouterType": {
    "id": 2,
    "code": "opentelekomNeutronRouter",
    "name": "Open Telekom Router",
    "description": "Neutron Router",
    "enabled": true,
    "creatable": true,
    "selectable": true,
    "hasFirewall": false,
    "hasDhcp": false,
    "hasRouting": false,
    "hasNetworkServer": false,
    "optionTypes": [
      {
        "id": 1023,
        "name": "enableSnat",
        "description": null,
        "code": "networkRouter.opentelekom.enableSnat",
        "fieldName": "enableSnat",
        "fieldLabel": "Enable SNAT",
        "fieldContext": "config",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "fieldInput": null,
        "placeHolder": null,
        "helpBlock": "",
        "defaultValue": null,
        "optionSource": "yesNo",
        "optionList": null,
        "type": "select",
        "advanced": false,
        "required": true,
        "editable": false,
        "creatable": true,
        "config": {
        },
        "displayOrder": 18,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "contextualDefault": false
      }
    ],
    "ruleOptionTypes": [

    ],
    "ruleGroupOptionTypes": [

    ],
    "natOptionTypes": [

    ],
    "bgpOptionTypes": [
    ]
  }
}

This endpoint retrieves a specific network router type. Use this API to retrieve list of available option types for a specific network router type.

HTTP Request

GET $serverUrl/api/network-router-types/:id

URL Parameters

Parameter Description
id The ID of the network router type

Get all Firewall Rule Groups for Network Router

curl "$serverUrl/api/networks/routers/1/firewall-rule-groups" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "ruleGroups": [
    {
      "id": 321,
      "name": "Policy_Default_Infra",
      "description": null,
      "externalId": "Policy_Default_Infra",
      "iacId": null,
      "zone": null,
      "zonePool": null,
      "status": "available",
      "priority": 20,
      "groupLayer": "Default",
      "rules": [
        {
          "id": 1056,
          "name": "dand-nsxt-t0-0425.1",
          "code": null,
          "enabled": true,
          "groupName": "Policy_Default_Infra",
          "direction": "any",
          "ruleType": "custom",
          "policy": "accept",
          "source": [
            "ANY"
          ],
          "sourceType": "cidr",
          "destination": [
            "ANY"
          ],
          "destinationType": "instance",
          "profiles": [
            "ANY"
          ],
          "protocol": null,
          "application": null,
          "applicationType": "port",
          "portRange": null,
          "sourcePortRange": null,
          "sourceGroup": null,
          "sourceTier": null,
          "applications": [
            {
              "id": 432,
              "name": "ANY"
            }
          ]
        }
      ]
    }
  ]
}

This endpoint retrieves all firewall rule groups for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/firewall-rule-groups

URL Parameters

Parameter Description
router_id The ID of the network router

Get a Firewall Rule Group for Network Router

curl "$serverUrl/api/networks/routers/1/firewall-rule-groups/488" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "ruleGroup": {
    "id": 488,
    "name": "Test Group",
    "description": "foo2",
    "externalId": "c85ab668-9de2-4e6b-a460-6a376f61e0f5",
    "iacId": null,
    "zone": null,
    "zonePool": null,
    "status": "available",
    "priority": 10,
    "groupLayer": "LocalGatewayRules",
    "rules": [
      {
        "id": 1444,
        "name": "api-test-rule-2",
        "code": null,
        "enabled": true,
        "groupName": "Test Group",
        "direction": "any",
        "ruleType": "custom",
        "policy": "accept",
        "source": [
          "ANY"
        ],
        "sourceType": "cidr",
        "destination": [
          "ANY"
        ],
        "destinationType": "instance",
        "profiles": [
          "ANY"
        ],
        "protocol": null,
        "application": null,
        "applicationType": "port",
        "portRange": null,
        "sourcePortRange": null,
        "sourceGroup": null,
        "sourceTier": null,
        "applications": [
          {
            "id": 466,
            "name": "ANY"
          }
        ]
      }
    ]
  }
}

This endpoint retrieves a firewall rule group for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/firewall-rule-groups/:group_id

URL Parameters

Parameter Description
router_id The ID of the network router
group_id The ID of the firewall rule group

Create a Network Router Firewall Rule Group

Use this command to create a firewall rule group for an existing network router.

curl -XPOST "$serverUrl/api/networks/routers/1/firewall-rule-groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "ruleGroup": {
          "name": "Test Group",
          "description": "Group description",
          "priority": 100,
          "externalType": "GatewayPolicy",
          "groupLayer": "LocalGatewayRules"
          }
      }'

The above command returns JSON Structured like this:

{
  "id": 800,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/routers/:router_id/firewall-rule-groups

URL Parameters

Parameter Description
router_id The ID of the network router

JSON Parameters

Parameter Required Description
name Y Firewall rule group name
description N Firewall rule group description
priority N Firewall rule group priority
externalType Y Platform / vendor specific type
groupLayer Y Platform / vendor specific category

Update Network Router Firewall Rule Group

curl -XPUT "$serverUrl/api/networks/routers/100/firewall-rule-groups/477" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "ruleGroup": {
          "name": "Test Group",
          "description": "Group description",
          "priority": 100
        }
      }'

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/routers/:id/firewall-rule-groups/:group_id

URL Parameters

Parameter Description
id The ID of the network router
group_id The ID of the firewall rule group

JSON Parameters

Parameter Required Description
name N Sets name of firewall rule group
description N Sets description of firewall rule group
priority N Sets priority of the firewall rule group

Delete a Network Router Firewall Rule Group

curl -XDELETE "$serverUrl/api/networks/routers/100/firewall-rule-groups/477" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a firewall rule group from a network router.

HTTP Request

DELETE $serverUrl/api/networks/routers/:router_id/firewall-rule-groups/:group_id

URL Parameters

Parameter Description
router_id The ID of the network router
group_id The ID of the firewall rule group to be deleted

Get all Network Router NATs for Network Router

curl "$serverUrl/api/networks/routers/99/nats" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouterNATs": [
    {
      "id": 11,
      "name": "api-test-nat",
      "description": "description",
      "enabled": true,
      "sourceNetwork": "1.1.1.1",
      "destinationNetwork": null,
      "translatedNetwork": "2.2.2.2",
      "sourcePorts": null,
      "destinationPorts": null,
      "translatedPorts": null,
      "priority": 100,
      "protocol": null,
      "matchIpv6DestinationPrefix": null,
      "translatedIpv4SourcePrefix": null,
      "refType": null,
      "refId": null,
      "syncSource": "external",
      "internalId": null,
      "externalId": "15efe516-af3a-4e37-af7b-dff5a62c6faa",
      "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0/nat/USER/nat-rules/15efe516-af3a-4e37-af7b-dff5a62c6faa",
      "dateCreated": "2021-07-20T12:54:46Z",
      "lastUpdated": "2021-07-20T12:56:11Z"
    }
  ]
}

This endpoint retrieves all NATs for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/nats

URL Parameters

Parameter Description
router_id The ID of the network router

Get a Network Router NAT

curl "$serverUrl/api/networks/routers/1/nats/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouterNAT": {
    "id": 11,
    "name": "api-test-nat",
    "description": "description",
    "enabled": true,
    "sourceNetwork": "1.1.1.1",
    "destinationNetwork": null,
    "translatedNetwork": "2.2.2.2",
    "sourcePorts": null,
    "destinationPorts": null,
    "translatedPorts": null,
    "priority": 100,
    "protocol": null,
    "matchIpv6DestinationPrefix": null,
    "translatedIpv4SourcePrefix": null,
    "refType": null,
    "refId": null,
    "syncSource": "external",
    "internalId": null,
    "externalId": "15efe516-af3a-4e37-af7b-dff5a62c6faa",
    "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0/nat/USER/nat-rules/15efe516-af3a-4e37-af7b-dff5a62c6faa",
    "dateCreated": "2021-07-20T12:54:46Z",
    "lastUpdated": "2021-07-20T12:56:11Z"
  }
}

This endpoint retrieves a network router NAT for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/nats/:nat_id

URL Parameters

Parameter Description
router_id The ID of the network router
nat_id The ID of the NAT

Create a Network Router NAT

Use this command to create a NAT for an existing network router.

curl -XPOST "$serverUrl/api/networks/routers/1/nats" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRouterNAT": {
          "name": "Name of NAT",
          "description": "Description of NAT",
          "enabled": "on",
          "config": {
            "action": "SNAT",
            "service": "/infra/services/TELNET",
            "firewall": "MATCH_INTERNAL_ADDRESS",
            "scope": null,
            "logging": "off"
         },
         "sourceNetwork": "1.1.1.1",
         "destinationNetwork": "1.2.3.4",
         "translatedNetwork": "2.2.2.2",
         "translatedPorts": "2222",
         "priority": 100
       }
     }'

The above command returns JSON Structured like this:

{
  "id": 800,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/routers/:router_id/nats

URL Parameters

Parameter Description
router_id The ID of the network router

JSON Parameters

Parameter Required Description
name Y NAT name

For a full list of available NAT options, see natOptionTypes in Get a Specific Network Router Type

Update Network Router NAT

curl -XPUT "$serverUrl/api/networks/routers/100/nats/477" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRouterNAT": {
          "name": "Test NAT",
        }
      }'

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/routers/:id/nats/:nat_id

URL Parameters

Parameter Description
id The ID of the network router
nat_id The ID of the network router NAT

JSON Parameters

Parameter Required Description
name N Sets name of NAT

For a full list of available NAT options, see natOptionTypes in Get a Specific Network Router Type

Delete a Network Router NAT

curl -XDELETE "$serverUrl/api/networks/routers/100/nats/477" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a NAT from a network router.

HTTP Request

DELETE $serverUrl/api/networks/routers/:router_id/nats/:nat_id

URL Parameters

Parameter Description
router_id The ID of the network router
nat_id The ID of the NAT to be deleted

Get all BGP Neighbors for Network Router

curl "$serverUrl/api/networks/routers/99/bgp-neighbors" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouterBgpNeighbors": [
    {
      "id": 15,
      "ipAddress": "172.16.2.22",
      "forwardingAddress": null,
      "protocolAddress": null,
      "remoteAs": "12345",
      "weight": 60,
      "keepAlive": 60,
      "holdDown": 180,
      "password": null,
      "routeFilteringType": "IPV4",
      "routeFilteringIn": "prefixlist-out-default",
      "routeFilteringOut": "prefixlist-out-default",
      "bfdEnabled": false,
      "bfdInterval": 1000,
      "bfdMultiple": 3,
      "allowAsIn": false,
      "hopLimit": 1,
      "restartMode": "HELPER_ONLY",
      "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0/locale-services/default/bgp/neighbors/d20fc560-35e3-11ec-b68f-c788e632ae30",
      "syncSource": "external",
      "internalId": null,
      "externalId": "d20fc560-35e3-11ec-b68f-c788e632ae30",
      "refType": null,
      "refId": null,
      "config": {
        "sourceAddresses": [
          "12.12.22.22",
          "10.22.12.2"
        ]
      },
      "dateCreated": "2021-10-25T22:37:54Z",
      "lastUpdated": "2021-10-27T15:08:12Z"
    }
  ]
}

This endpoint retrieves all BGP Neighbors for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/bgp-neighbors

URL Parameters

Parameter Description
router_id The ID of the network router

Get a Network Router BGP Neighbor

curl "$serverUrl/api/networks/routers/1/bgp-neighbors/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkRouterBgpNeighbor": {
    "id": 15,
    "ipAddress": "172.16.2.22",
    "forwardingAddress": null,
    "protocolAddress": null,
    "remoteAs": "21345",
    "weight": 60,
    "keepAlive": 60,
    "holdDown": 180,
    "password": null,
    "routeFilteringType": "IPV4",
    "routeFilteringIn": "prefixlist-out-default",
    "routeFilteringOut": "prefixlist-out-default",
    "bfdEnabled": false,
    "bfdInterval": 1000,
    "bfdMultiple": 3,
    "allowAsIn": false,
    "hopLimit": 1,
    "restartMode": "HELPER_ONLY",
    "providerId": "/infra/tier-0s/b05d6532-2742-4dbd-98f2-a62aa8a62ae0/locale-services/default/bgp/neighbors/d20fc560-35e3-11ec-b68f-c788e632ae30",
    "syncSource": "external",
    "internalId": null,
    "externalId": "d20fc560-35e3-11ec-b68f-c788e632ae30",
    "refType": null,
    "refId": null,
    "config": {
      "sourceAddresses": [
        "12.12.22.22",
        "10.22.12.2"
      ]
    },
    "dateCreated": "2021-10-25T22:37:54Z",
    "lastUpdated": "2021-10-27T15:08:12Z"
  }
}

This endpoint retrieves a network router BGP Neighbor for specified network router.

HTTP Request

GET $serverUrl/api/networks/routers/:router_id/bgp-neighbors/:bgp_neighbor_id

URL Parameters

Parameter Description
router_id The ID of the network router
bgp_neighbor_id The ID of the BGP neighbor

Create a Network Router BGP Neighbor

Use this command to create a BGP Neighbor for an existing network router.

curl -XPOST "$serverUrl/api/networks/routers/1/bgp-neighbors" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRouterBgpNeighbor": {
          "ipAddress": "172.16.2.23",
          "config": {
              "sourceAddresses": [
                  "10.22.12.2"
              ]
          },
          "remoteAs": "21346",
          "keepAlive": 60,
          "holdDown": 180,
          "routeFilteringType": "IPV4",
          "routeFilteringIn": "prefixlist-out-default",
          "routeFilteringOut": "prefixlist-out-default",
          "bfdEnabled": "off",
          "bfdInterval": 1000,
          "bfdMultiple": 3,
          "allowAsIn": "off",
          "hopLimit": 1,
          "restartMode": "HELPER_ONLY"
        }
     }'

The above command returns JSON Structured like this:

{
  "id": 800,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/routers/:router_id/bgp-neighbors

URL Parameters

Parameter Description
router_id The ID of the network router

For a full list of available options, see bgpOptionTypes in Get a Specific Network Router Type

Update Network Router BGP Neighbor

curl -XPUT "$serverUrl/api/networks/routers/1/bgp-neighbors/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "networkRouterBgpNeighbor": {
          "ipAddress": "172.16.0.1",
        }
      }'

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/networks/routers/:id/bgp-neighbors/:bgp_neighbor_id

URL Parameters

Parameter Description
id The ID of the network router
bgp_neighbor_id The ID of the network router BGP neighbor

For a full list of available BGP Neighbor options, see bgpOptionTypes in Get a Specific Network Router Type

Delete a Network Router BGP Neighbor

curl -XDELETE "$serverUrl/api/networks/routers/100/bgp-neighbors/477" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a BGP Neighbor from a network router.

HTTP Request

DELETE $serverUrl/api/networks/routers/:router_id/bgp-neighbors/:bgp_neighbor_id

URL Parameters

Parameter Description
router_id The ID of the network router
bgp_neighbor_id The ID of the BGP Neighbor to be deleted

Network Services

Provides API for managing Network Services.

Only the list endpoint is currently the only available endpoint. Network Service management will be available with the Integration API endpoints.

Get All Network Services

curl "$serverUrl/api/networks/services"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkServices": [
    {
      "serviceType": "networkPool",
      "serviceTypeName": "Network Pool",
      "type": "phpipam",
      "typeName": "phpIPAM",
      "name": "phpIPAM",
      "id": 30,
      "integrationId": 26
    },
    {
      "serviceType": "dns",
      "serviceTypeName": "DNS",
      "type": "amazonDns",
      "name": "aws-cloud",
      "id": 31,
      "integrationId": 31,
      "typeName": "Route 53"
    }
  ]
}

This endpoint retrieves all Network Services associated with the account.

HTTP Request

GET $serverUrl/api/networks/services

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Network Transport Zones

Provides API interfaces for managing Network Transport Zones for a Network Service within Morpheus.

Get all Network Transport Zones for Network Server

curl "$serverUrl/api/networks/servers/1/scopes" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkScopes": [
    {
      "id": 1,
      "internalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "visibility": "private",
      "dateCreated": "2021-11-03T14:23:17Z",
      "providerId": "/xxxx/xx/xxxx/xxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "lastUpdated": "2021-11-03T14:25:05Z",
      "active": true,
      "streamType": "OVERLAY",
      "displayName": "transport-zone-a",
      "name": "transport-zone-a",
      "status": "ok",
      "enabled": true,
      "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "config": {
        "nvdsName": "transport-zone-a",
        "hostMembershipCriteria": "STANDARD"
      },
      "owner": {
        "id": 1
      },
      "networkServer": {
        "id": 13
      },
      "zone": {
        "id": 20
      },
      "tenants": [
        {
          "id": 1,
          "name": "Stubby Toes Inc."
        }
      ]
    }
  ],
  "meta": {
    "max": "25",
    "offset": "0",
    "sort": "name",
    "order": "asc",
    "total": 1
  }
}

This endpoint retrieves all Network Transport Zones for a specified Network Service.

HTTP Request

GET $serverUrl/api/networks/servers/:id/scopes

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load network transport zones that contain the phrase specified in name or description

Get a Specific Network Transport Zone

curl "$serverUrl/api/networks/servers/1/scopes/1" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "networkScope": {
    "id": 1,
    "internalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "visibility": "private",
    "dateCreated": "2021-11-03T14:23:17Z",
    "providerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "lastUpdated": "2021-11-03T14:25:05Z",
    "active": true,
    "streamType": "OVERLAY",
    "displayName": "transport-zone-a",
    "name": "transport-zone-a",
    "status": "ok",
    "enabled": true,
    "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "config": {
      "nvdsName": "transport-zone-a",
      "hostMembershipCriteria": "STANDARD"
    },
    "owner": {
      "id": 1
    },
    "networkServer": {
      "id": 13
    },
    "zone": {
      "id": 20
    },
    "tenants": [
      {
        "id": 1,
        "name": "Stubby Toes Inc."
      }
    ]
  }
}

This endpoint retrieves a specific network transport zone.

HTTP Request

GET $serverUrl/api/networks/servers/:serverId/scopes/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the network transport zone

Create a Network Transport Zone

Use this command to create a network transport zone.

curl -XPOST "$serverUrl/api/networks/servers/1/scopes" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
  "networkScope": {
    "name": "stubby-toes-tz",
    "description": null,
    "visibility": "public",
    "tenants": [
      {
        "id": 1
      },
      {
        "id": 2
      }
    ]
  }
}'

The above command returns JSON Structured like this:

{
  "id": 1,
  "success": true
}

HTTP Request

POST $serverUrl/api/networks/servers/:serverId/scopes

JSON Parameters

The parameters for creating a network transport zone is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Required Description
name Y Network transport zone name
description N Network transport zone description
visibility N private or public
tenants N Array of tenant account ids that are allowed access

Update a Network Transport Zone

Use this command to update an existing network transport zone.

curl -XPUT "$serverUrl/api/networks/servers/1/scopes/1" \
-H "Authorization: BEARER $accessToken"
-H "Content-Type: application/json" \
-d '{
  "networkScope": {
    "name": "stubby-toes-tz",
    "description": null,
    "visibility": "public",
    "tenants": [
      {
        "id": 1
      },
      {
        "id": 2
      }
    ]
  }
}'

The above command returns JSON structured like this:

{
"success": true
}

HTTP Request

PUT $serverUrl/api/networks/servers/:serverId/scopes/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the network transport zone

JSON Parameters

The parameters for update a network transport zone is type dependent. The following lists the common parameters. See get a specific type to list available options for the network server type.

Parameter Description
name Network transport zone name
description Network transport zone description
visibility private or public
tenants Array of tenant account ids that are allowed access

Delete a Network Transport Zone

curl -XDELETE "$serverUrl/api/networks/servers/1/scopes/1" \
-H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
    "success": true
}

Will delete a network transport zone.

HTTP Request

DELETE $serverUrl/api/networks/servers/:serverId/scopes/:id

URL Parameters

Parameter Description
serverId ID of the network server
id ID of the network transport zone

Security Groups

A Security Group is a grouping of rules. Each rule is a whitelist entry for a particular IP address to either a port range or a particular Morpheus instance type. A Security Group may be applied to multiple Clouds, Apps, and Instances.

Get All Security Groups

curl "$serverUrl/api/security-groups"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "securityGroups": [
    {
      "id": 18,
      "name": "Colorado office",
      "description": "All the Colorado office to access anywhere",
      "accountId": 1,
      "groupSource": null,
      "externalId": null,
      "enabled": null,
      "syncSource": "internal",
      "visibility": "private",
      "active": true,
      "zone": null,
      "locations": [
        {
          "id": 429,
          "name": "Colorado office",
          "externalId": "sg-01c120cf02de97410",
          "iacId": null,
          "zone": {
            "id": 8,
            "name": "test-aws"
          },
          "zonePool": null,
          "status": "available"
        }
      ],
      "rules": [
        {
          "id": 30,
          "name": "my app ports",
          "ruleType": "customRule",
          "customRule": true,
          "instanceTypeId": null
          "direction": "ingress",
          "policy": "accept",
          "sourceType": "cidr",
          "source": "0.0.0.0/0",
          "sourceGroup": null,
          "sourceTier": null,
          "portRange": "5565-5570",
          "protocol": "tcp",
          "destinationType": "instance",
          "destination": null,
          "destinationGroup": null,
          "destinationTier": null,
          "externalId": null,
          "enabled": null,
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all security groups and their JSON encoded configuration attributes.

HTTP Request

GET $serverUrl/api/security-groups

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Name or description filter, restricts query to only load security groups which contain the phrase specified

Get a Specific Security Group

curl "$serverUrl/api/security-groups/18" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "securityGroup": {
    "id": 18,
    "name": "Colorado office",
    "description": "All the Colorado office to access anywhere",
    "accountId": 1,
    "groupSource": null,
    "externalId": null,
    "enabled": null,
    "syncSource": "internal",
    "visibility": "private",
    "active": true,
    "zone": null,
    "locations": [
      {
        "id": 429,
        "name": "Colorado office",
        "externalId": "sg-01c120cf02de97410",
        "iacId": null,
        "zone": {
          "id": 8,
          "name": "bertramlabs-aws"
        },
        "zonePool": null,
        "status": "available"
      }
    ],
    "rules": []
  }
}

This endpoint retrieves a specific security group.

HTTP Request

GET $serverUrl/api/security-groups/:id

URL Parameters

Parameter Description
id The ID of the security group

Create a Security Group

curl -XPOST "$serverUrl/api/security-groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "securityGroup": {
  "name": "My New Security Group",
  "description": "My Description"
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single security group

HTTP Request

POST $serverUrl/api/security-groups

JSON Security Group Parameters

Parameter Default Description
name Name for your security group
description Optional description field
zoneId Scoped Cloud ID.
active Set to false to disable a security group.
customOptions.vpc External ID of Amazon VPC.
customOptions.resourceGroup External ID of the Azure Resource Group to scope to.
tenantPermissions.accounts Array of tenant account ids that are allowed access.
tenantPermissions.canManageAccounts Array of tenant account ids that can manage.
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

Updating a Security Group

curl -XPUT "$serverUrl/api/security-groups/18" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "securityGroup": {
  "name": "My New Security Group",
  "description": "My Description"
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single security group

HTTP Request

PUT $serverUrl/api/security-groups/:id

URL Parameters

Parameter Description
id The ID of the security group

JSON Security Group Parameters

Parameter Default Description
name Name for your security group
description Optional description field
active Set to false to disable a security group.
tenantPermissions.accounts Array of tenant account ids that are allowed access
tenantPermissions.canManageAccounts Array of tenant account ids that can manage.
resourcePermissions.all Pass true to allow access all groups
resourcePermissions.sites Array of groups that are allowed access

Delete a Security Group

curl -XDELETE "$serverUrl/api/security-groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a security group and update all clouds, apps, and instances which are currently using the security group.

HTTP Request

DELETE $serverUrl/api/security-groups/:id

URL Parameters

Parameter Description
id The ID of the security group

Create a Security Group Location

curl -XPOST "$serverUrl/api/security-groups/18/locations" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "securityGroupLocation": {
    "zoneId": 5,
    "customOptions": {
      "resourceGroup": 1
    },
    }}'

The above command returns a similar JSON structure when submitting a GET request for a single security group rule

Will add a security group to the specified cloud.

HTTP Request

POST $serverUrl/api/security-groups/:id/locations

JSON Security Group Location Parameters

Parameter Default Description
zoneId The ID of the Zone (Cloud)
customOptions.vpc External ID of Amazon VPC.
customOptions.resourceGroup External ID of the Azure Resource Group to scope to.

Delete a Security Group Location

curl -XDELETE "$serverUrl/api/security-groups/18/locations/29" \
  -H "Authorization: BEARER $accessToken"

The above command returns a similar JSON structure when submitting a GET request for a single security group rule

Will remove a security group from a cloud.

HTTP Request

DELETE $serverUrl/api/security-groups/:id/locations/:locationId

URL Parameters

Parameter Description
id The ID of the security group
locationId The ID of the security group location

Security Group Rules

A Security Group Rule specifies that a certain CIDR is able to access a particular port (or port range) for a particular protocol. Or, that a particular CIDR is able to access all instances of a particular type (like MySql, Redis, etc). A Security Group Rule belongs to a Security Group and a Security Group is applied to either a Cloud, App, or Instance.

curl "$serverUrl/api/security-groups/19/rules"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "rules": [
    {
      "id": 29,
      "name": "my-sg port 5555",
      "ruleType": "customRule",
      "customRule": true,
      "instanceTypeId": null
      "direction": "ingress",
      "policy": "accept",
      "sourceType": "group",
      "source": null,
      "sourceGroup": {
        "id": 2239,
        "name": "my-sg"
      },
      "sourceTier": null,
      "portRange": "5555",
      "protocol": "tcp",
      "destinationType": "instance",
      "destination": null,
      "destinationGroup": null,
      "destinationTier": null,
      "externalId": null,
      "enabled": null,
      "syncSource": "external"
    },
    {
      "id": 30,
      "name": "my app ports",
      "ruleType": "customRule",
      "customRule": true,
      "instanceTypeId": null
      "direction": "ingress",
      "policy": "accept",
      "sourceType": "cidr",
      "source": "0.0.0.0/0",
      "sourceGroup": null,
      "sourceTier": null,
      "portRange": "5565-5570",
      "protocol": "tcp",
      "destinationType": "instance",
      "destination": null,
      "destinationGroup": null,
      "destinationTier": null,
      "externalId": null,
      "enabled": null,
    }
  ]
}

This endpoint retrieves all security group rules for a Security Gorup.

HTTP Request

GET $serverUrl/api/security-groups/:id/rules

Get a Specific Security Group Rule

curl "$serverUrl/api/security-groups/19/rules/30" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "rule": {
      "id": 30,
      "name": "my app ports",
      "ruleType": "customRule",
      "customRule": true,
      "instanceTypeId": null
      "direction": "ingress",
      "policy": "accept",
      "sourceType": "cidr",
      "source": "0.0.0.0/0",
      "sourceGroup": null,
      "sourceTier": null,
      "portRange": "5565-5570",
      "protocol": "tcp",
      "destinationType": "instance",
      "destination": null,
      "destinationGroup": null,
      "destinationTier": null,
      "externalId": null,
      "enabled": null,
    }
}

This endpoint retrieves a specific security group rule.

HTTP Request

GET $serverUrl/api/security-groups/:id/rules/:id

Create a Security Group Rule

curl -XPOST "$serverUrl/api/security-groups/19/rules" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "rule": {
    "name": "port 55",
    "sourceType": "cidr",
    "source": "50.22.10.10/32",
    "portRange": "55",
    "protocol": "tcp",
    "destinationType": "instance",
    "customRule": true,
    "instanceTypeId": null
    }}'

The above command returns a similar JSON structure when submitting a GET request for a single security group rule

Will create a security group rule and update all clouds, apps, and instances which are currently using the security group in which this rule belongs.

HTTP Request

POST $serverUrl/api/security-groups/:id/rules

JSON Security Group Rule Parameters

Parameter Default Description
name A name for the rule
direction ingress Either ingress or egress.
source CIDR representing the source IP(s) which should receive
sourceType cidr Either cidr, group, tier, all.
source CIDR representing the source IP(s) which should receive access. Required for sourceType=cidr.
sourceGroup.id The source Security Group ID. Required for sourceType=group.
sourceTier.id The source Tier ID. Required for soureType=tier.
portRange Either a single value (i.e. 55) or a port range (i.e. 1-65535) for which to open access to the source. Required if customRule is true, otherwise, ignored.
protocol Either tcp, udp, icmp. Required if customRule is true, otherwise, ignored.
destinationType cidr Either cidr, group, tier, instance.
destination CIDR representing the destination IP(s) which should receive access. Required for destinationType=cidr.
destinationGroup.id The destination Security Group ID. Required for destinationType=group.
destinationTier.id The destination Tier ID. Required for destinationType=tier.
ruleType customRule Either customRule or an instance type code.
policy accept Either accept or deny.
instanceTypeId The id of an Instance Type. If specified, the source CIDR will have access to all ports exposed by the particular instance in the cloud, app, or instance. Required if customRule is false, otherwise ignored.

Updating a Security Group Rule

curl -XPUT "$serverUrl/api/security-groups/19/rules/30" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{ "rule": {
    "portRange": "55-56"
    }}'

The above command returns a similar JSON structure when submitting a GET request for a single security group rule

Will update a security group rule and update all clouds, apps, and instances which are currently using the security group in which this rule belongs.

HTTP Request

PUT $serverUrl/api/security-groups/:id/rules/:id

JSON Security Group Rule Parameters

Same parameters as specified in the creation of a Security Group Rule

Delete a Security Group Rule

curl -XDELETE "$serverUrl/api/security-groups/19/rules/30" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a security group rule and update all clouds, apps, and instances which are currently using the security group in which this rule belongs.

HTTP Request

DELETE $serverUrl/api/security-groups/:id/rules/:id

Load Balancers

Provides API for managing Load Balancers.

Get All Load Balancers

curl "$serverUrl/api/load-balancers"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "loadBalancers": [
    {
      "id": 80,
      "name": "dand-nsxt",
      "accountId": 1,
      "cloud": {
        "id": 75,
        "name": "vmware-nsx"
      },
      "type": {
        "id": 19,
        "name": "NSX-T",
        "code": "nsx-t"
      },
      "visibility": "public",
      "description": "",
      "host": "10.32.23.7",
      "port": 22,
      "username": null,
      "ip": "10.32.23.7",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "sslEnabled": null,
      "sslCert": null,
      "config": {
        "loglevel": "INFO",
        "tier1": "/infra/tier-1s/4286ddad-3d8a-464b-81a8-e17e15f30ca8",
        "size": "SMALL",
        "adminState": true,
        "systemVersion": "2.5.1.0.0.15314292"
      },
      "dateCreated": "2021-10-19T17:32:05Z",
      "lastUpdated": "2021-12-03T18:52:47Z"
    },
    {
      "id": 115,
      "name": "dand-tenant-nsxt-lb",
      "accountId": 1,
      "cloud": {
        "id": 75,
        "name": "vmware-nsx"
      },
      "type": {
        "id": 19,
        "name": "NSX-T",
        "code": "nsx-t"
      },
      "visibility": "public",
      "description": "",
      "host": "10.32.23.7",
      "port": 22,
      "username": null,
      "ip": "10.32.23.7",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "sslEnabled": null,
      "sslCert": null,
      "config": {
        "loglevel": "INFO",
        "tier1": null,
        "size": "SMALL",
        "adminState": true,
        "serverVersion": null,
        "systemVersion": "2.5.1.0.0.15314292"
      },
      "dateCreated": "2021-11-18T16:53:16Z",
      "lastUpdated": "2021-12-03T18:52:43Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 2,
    "size": 2,
    "total": 6
  }
}

This endpoint retrieves all load balancers associated with the account.

HTTP Request

GET $serverUrl/api/load-balancers

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Load Balancer

curl "$serverUrl/api/load-balancers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "loadBalancer": {
    "id": 80,
    "name": "dand-nsxt",
    "accountId": 1,
    "cloud": {
      "id": 75,
      "name": "vmware-nsx"
    },
    "type": {
      "id": 19,
      "name": "NSX-T",
      "code": "nsx-t"
    },
    "visibility": "public",
    "description": "",
    "host": "10.32.23.7",
    "port": 22,
    "username": null,
    "ip": "10.32.23.7",
    "internalIp": null,
    "externalIp": null,
    "apiPort": null,
    "adminPort": null,
    "sslEnabled": null,
    "sslCert": null,
    "config": {
      "loglevel": "INFO",
      "tier1": "/infra/tier-1s/4286ddad-3d8a-464b-81a8-e17e15f30ca8",
      "size": "SMALL",
      "adminState": true,
      "systemVersion": "2.5.1.0.0.15314292"
    },
    "dateCreated": "2021-10-19T17:32:05Z",
    "lastUpdated": "2021-12-03T18:52:47Z"
  }
}

This endpoint retrieves a specific Load Balancer.

HTTP Request

GET $serverUrl/api/load-balancers/:id

URL Parameters

Parameter Description
ID The ID of the Load Balancer to retrieve

Create a Load Balancer

curl -XPOST "$serverUrl/api/load-balancers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancer": {
    "type": "nsx-t",
    "networkServerId": 23,
    "name": "lab-nsxt",
    "enabled": true,
    "config": {
      "adminState": true,
      "size": "SMALL",
      "loglevel": "INFO"
    },
    "resourcePermission": {
      "all": true
    },
    "tenants": [
      {
        "id": 2
      },
      {
        "id": 1
      }
    ],
    "visibility": "private"
  }
}'

The above command returns JSON structured like getting a single Load Balancer:

Available for NSX-T load balancers only

Use this command to create a load balancer.

HTTP Request

POST $serverUrl/api/load-balancers

JSON Parameters

Parameter Default Description
name Name
description Description
networkServerId Network Server ID
config Configuration object with parameters that vary by type.
visibility public private or public
tenants Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access to all groups
resourcePermissions.sites Array of groups that are allowed access

This endpoint allows creating a Load Balancer. Only certain types of clouds support creating and deleting load balancers. Configuration options vary by Load Balancer Type.

Update a Load Balancer

curl -XPUT "$serverUrl/api/load-balancers/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancer": {
    "description": "new description"
  }
}'

The above command returns JSON structured like getting a single Load Balancer:

Available for NSX-T load balancers only

Use this command to update an existing load balancer.

HTTP Request

PUT $serverUrl/api/load-balancers/:id

URL Parameters

Parameter Description
ID The ID of the Load Balancer

JSON Parameters

Parameter Default Description
name Name
description Description
enabled Activate (true) or disable (false)
config Configuration object with parameters that vary by type.
visibility public private or public
tenants Array of tenant account ids that are allowed access
resourcePermissions.all Pass true to allow access to all groups
resourcePermissions.sites Array of groups that are allowed access

This endpoint allows updating a Load Balancer. Configuration options vary by Load Balancer Type.

Refresh a Load Balancer

curl -XPUT "$serverUrl/api/load-balancers/:id/refresh" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true,
  "loadBalancer": {
    "id": 80,
    "name": "dand-nsxt",
    "accountId": 1,
    "cloud": {
      "id": 75,
      "name": "vmware-nsx"
    },
    "type": {
      "id": 19,
      "name": "NSX-T",
      "code": "nsx-t"
    },
    "visibility": "public",
    "description": "",
    "host": "10.32.23.7",
    "port": 22,
    "username": null,
    "ip": "10.32.23.7",
    "internalIp": null,
    "externalIp": null,
    "apiPort": null,
    "adminPort": null,
    "sslEnabled": null,
    "sslCert": null,
    "config": {
      "loglevel": "INFO",
      "tier1": "/infra/tier-1s/4286ddad-3d8a-464b-81a8-e17e15f30ca8",
      "size": "SMALL",
      "adminState": true,
      "systemVersion": "2.5.1.0.0.15314292"
    },
    "dateCreated": "2021-10-19T17:32:05Z",
    "lastUpdated": "2021-12-03T18:52:47Z"
  }
}

Will refresh a Load Balancer.

HTTP Request

PUT $serverUrl/api/load-balancers/:id/refresh

URL Parameters

Parameter Description
ID The ID of the Load Balancer

Delete a Load Balancer

curl -XDELETE "$serverUrl/api/load-balancers/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Load Balancer from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/load-balancers/:id

URL Parameters

Parameter Description
ID The ID of the Load Balancer

Load Balancer Types

Provides API for viewing Load Balancer Types and their configuration options.

Get All Load Balancer Types

curl "$serverUrl/api/load-balancer-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "loadBalancerTypes": [
    {
      "id": 7,
      "name": "A10 (aXAPI v3)",
      "code": "a10AXvThunder",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 10,
      "name": "Amazon ALB",
      "code": "amazon-alb",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 8,
      "name": "AVI",
      "code": "avi",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 9,
      "name": "Azure Load Balancer",
      "code": "azure",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 13,
      "name": "Citrix NetScaler",
      "code": "netScaler",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 5,
      "name": "F5 BigIP (v11.4+)",
      "code": "bigip",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 14,
      "name": "FortiADC",
      "code": "fortiadc",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 11,
      "name": "HAProxy Container",
      "code": "haproxyContainer",
      "enabled": true,
      "internal": true,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    },
    {
      "id": 19,
      "name": "NSX-T",
      "code": "nsx-t",
      "enabled": true,
      "internal": false,
      "creatable": true,
      "createType": "multi",
      "optionTypes": [

      ],
      "vipOptionTypes": [

      ]
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 9,
    "total": 9
  }
}

This endpoint retrieves all Load Balancer Types.

HTTP Request

GET $serverUrl/api/load-balancer-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
optionTypes false Pass true to include optionTypes in the response for each load balancer type.
phrase Filter by wildcard search of name and code
name Filter by name
code Filter by code

Get a Specific Load Balancer Type

curl "$serverUrl/api/load-balancer-types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "loadBalancerType": {
    "id": 19,
    "name": "NSX-T",
    "code": "nsx-t",
    "enabled": true,
    "internal": false,
    "creatable": true,
    "createType": "multi",
    "optionTypes": [],
    "vipOptionTypes": []
  }
}

This endpoint will retrieve a specific load balancer type by id.

HTTP Request

GET $serverUrl/api/load-balancer-types/:id

URL Parameters

Parameter Description
ID The ID of the load balancer type

Load Balancer Virtual Servers

Provides API for managing Load Balancer Virtual Servers.

Get All Load Balancer Virtual Servers For Load Balancer

curl "$serverUrl/api/load-balancers/1/virtual-servers"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "loadBalancerInstances": [
    {
      "id": 5,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "instance": null,
      "description": null,
      "internalId": "/infra/lb-virtual-servers/ba4dacf1-1f1c-47fe-a0cd-70344521391c",
      "externalId": "ba4dacf1-1f1c-47fe-a0cd-70344521391c",
      "dateCreated": "2021-11-09T17:11:06Z",
      "lastUpdated": "2021-11-16T20:00:13Z",
      "active": true,
      "sticky": false,
      "sslEnabled": null,
      "externalAddress": false,
      "backendPort": null,
      "vipType": null,
      "vipAddress": "10.11.12.13",
      "vipHostname": null,
      "vipProtocol": "http",
      "vipScheme": null,
      "vipMode": null,
      "vipName": "db-1109",
      "vipPort": 80,
      "vipSticky": null,
      "vipBalance": null,
      "servicePort": null,
      "sourceAddress": null,
      "sslCert": {
        "id": 272,
        "name": "bob-apache-lb"
      },
      "sslMode": null,
      "sslRedirectMode": null,
      "vipShared": false,
      "vipDirectAddress": null,
      "serverName": null,
      "poolName": null,
      "removing": false,
      "vipSource": "user",
      "extraConfig": null,
      "serviceAccess": null,
      "networkId": null,
      "subnetId": null,
      "externalPortId": null,
      "status": "online",
      "vipStatus": "online"
    },
    {
      "id": 1,
      "loadBalancer": {
        "id": 2,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dd-nsxt-1",
        "ip": "10.32.23.7"
      },
      "instance": null,
      "description": null,
      "internalId": "/infra/lb-virtual-servers/93bd9df9-966b-4698-8dc0-1431295df6a4",
      "externalId": "93bd9df9-966b-4698-8dc0-1431295df6a4",
      "dateCreated": "2021-07-06T18:33:03Z",
      "lastUpdated": "2021-11-16T20:00:13Z",
      "active": true,
      "sticky": false,
      "sslEnabled": null,
      "externalAddress": false,
      "backendPort": null,
      "vipType": null,
      "vipAddress": "192.168.2.2",
      "vipHostname": null,
      "vipProtocol": "http",
      "vipScheme": null,
      "vipMode": null,
      "vipName": "dd-nsx-test2",
      "vipPort": 8080,
      "vipSticky": null,
      "vipBalance": null,
      "servicePort": null,
      "sourceAddress": null,
      "sslCert": null,
      "sslMode": null,
      "sslRedirectMode": null,
      "vipShared": false,
      "vipDirectAddress": null,
      "serverName": null,
      "poolName": null,
      "removing": false,
      "vipSource": "user",
      "extraConfig": null,
      "serviceAccess": null,
      "networkId": null,
      "subnetId": null,
      "externalPortId": null,
      "status": "online",
      "vipStatus": "online"
    },
    {
      "id": 2,
      "loadBalancer": {
        "id": 2,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dd-nsxt-1",
        "ip": "10.32.23.7"
      },
      "instance": null,
      "description": null,
      "internalId": "/infra/lb-virtual-servers/e4844ef6-ed50-4259-8687-6abe0adba890",
      "externalId": "e4844ef6-ed50-4259-8687-6abe0adba890",
      "dateCreated": "2021-07-06T18:33:03Z",
      "lastUpdated": "2021-11-16T20:00:13Z",
      "active": true,
      "sticky": false,
      "sslEnabled": null,
      "externalAddress": false,
      "backendPort": null,
      "vipType": null,
      "vipAddress": "192.168.212.95",
      "vipHostname": null,
      "vipProtocol": "http",
      "vipScheme": null,
      "vipMode": null,
      "vipName": "dd-nsxt-vs-1",
      "vipPort": 80,
      "vipSticky": null,
      "vipBalance": null,
      "servicePort": null,
      "sourceAddress": null,
      "sslCert": null,
      "sslMode": null,
      "sslRedirectMode": null,
      "vipShared": false,
      "vipDirectAddress": null,
      "serverName": null,
      "poolName": null,
      "removing": false,
      "vipSource": "user",
      "extraConfig": null,
      "serviceAccess": null,
      "networkId": null,
      "subnetId": null,
      "externalPortId": null,
      "status": "online",
      "vipStatus": "online"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 3,
    "total": 3
  }
}

This endpoint retrieves load balancer virtual servers associated with a specified load balancer.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/virtual-servers

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort vipName Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on vipName, vipHostname or vipAddress
vipName If specified will return an exact match on vipName
vipAddress If specified will return an exact match on vipAddress
vipHostname If specified will return an exact match on vipHostname

Get a Specific Load Balancer Virtual Server

curl "$serverUrl/api/load-balancers/1/virtual-servers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "loadBalancerInstance": {
    "id": 1,
    "loadBalancer": {
      "id": 2,
      "type": {
        "id": 19,
        "code": "nsx-t",
        "name": "NSX-T"
      },
      "name": "dd-nsxt-1",
      "ip": "10.32.23.7"
    },
    "instance": null,
    "description": null,
    "internalId": "/infra/lb-virtual-servers/93bd9df9-966b-4698-8dc0-1431295df6a4",
    "externalId": "93bd9df9-966b-4698-8dc0-1431295df6a4",
    "dateCreated": "2021-07-06T18:33:03Z",
    "lastUpdated": "2021-11-16T20:00:13Z",
    "active": true,
    "sticky": false,
    "sslEnabled": null,
    "externalAddress": false,
    "backendPort": null,
    "vipType": null,
    "vipAddress": "192.168.2.2",
    "vipHostname": null,
    "vipProtocol": "http",
    "vipScheme": null,
    "vipMode": null,
    "vipName": "dd-nsx-test2",
    "vipPort": 8080,
    "vipSticky": null,
    "vipBalance": null,
    "servicePort": null,
    "sourceAddress": null,
    "sslCert": null,
    "sslMode": null,
    "sslRedirectMode": null,
    "vipShared": false,
    "vipDirectAddress": null,
    "serverName": null,
    "poolName": null,
    "removing": false,
    "vipSource": "user",
    "extraConfig": null,
    "serviceAccess": null,
    "networkId": null,
    "subnetId": null,
    "externalPortId": null,
    "status": "online",
    "vipStatus": "online"
  }
}

This endpoint retrieves a specific Load Balancer Virtual Server.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/virtual-servers/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
id The ID of the Load Balancer Virtual Server to retrieve

Create a Load Balancer Virtual Server

curl -XPOST "$serverUrl/api/load-balancers/1/virtual-servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerInstance": {
    "vipName": "test virtual server",
    "description": "a test virtual server",
    "vipAddress": "10.11.12.13",
    "vipPort": "80",
    "vipProtocol": "http",
    "sslCert": 0,
    "sslServerCert": 0
  }
}'

The above command returns JSON structured like getting a single Load Balancer Virtual Server:

Use this command to create a load balancer virtual server.

HTTP Request

POST $serverUrl/api/load-balancers/:loadBalancerId/virtual-servers

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

JSON Parameters

Parameter Default Description
vipName VIP Name
description Description
vipAddress VIP Address
vipPort VIP Port
vipProtocol VIP Protocol
vipHostname VIP Hostname
pool Load Balancer Pool ID
sslCert SSL Client Certificate ID
sslServerCert SSL Server Certificate ID
config Configuration object with parameters that vary by type.

This endpoint allows creating a Load Balancer Virtual Server. Configuration options vary by Load Balancer Type.

Update a Load Balancer Virtual Server

curl -XPUT "$serverUrl/api/load-balancers/:loadBalancerId/virtual-servers/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerInstance": {
    "description": "new description"
  }
}'

The above command returns JSON structured like getting a single Load Balancer Virtual Server:

Use this command to update an exiting load balancer virtual server.

HTTP Request

PUT $serverUrl/api/load-balancers/:loadBalancerId/virtual-servers/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
id The ID of the Load Balancer Virtual Server

JSON Parameters

Parameter Default Description
vipName VIP Name
description Description
vipAddress VIP Address
vipPort VIP Port
vipProtocol VIP Protocol
vipHostname VIP Hostname
pool Load Balancer Pool ID
sslCert SSL Client Certificate ID
sslServerCert SSL Server Certificate ID
config Configuration object with parameters that vary by type.

This endpoint allows updating a Load Balancer Virtual Server. Configuration options vary by Load Balancer Type.

Delete a Load Balancer Virtual Server

curl -XDELETE "$serverUrl/api/load-balancers/:loadBalancerId/virtual-servers/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Load Balancer Virtual Server from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/load-balancers/:loadBalancerId/virtual-servers/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
id The ID of the Load Balancer Virtual Server

Load Balancer Pools

Provides API for managing Load Balancer Pools.

Get All Load Balancer Pools For Load Balancer

curl "$serverUrl/api/load-balancers/:loadBalancerId/pools"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "loadBalancerPools": [
    {
      "id": 63,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "bob-test-pool",
      "category": null,
      "visibility": "public",
      "description": "",
      "internalId": "/infra/lb-pools/7d971e87-4e99-4a5a-a00f-0636f3431bdc",
      "externalId": "7d971e87-4e99-4a5a-a00f-0636f3431bdc",
      "enabled": true,
      "vipSticky": null,
      "vipBalance": "ROUND_ROBIN",
      "allowNat": null,
      "allowSnat": null,
      "vipClientIpMode": null,
      "vipServerIpMode": null,
      "minActive": 2,
      "minInService": null,
      "minUpMonitor": null,
      "minUpAction": null,
      "maxQueueDepth": null,
      "maxQueueTime": null,
      "numberActive": 0,
      "numberInService": 0,
      "healthScore": 100.0,
      "performanceScore": 100.0,
      "healthPenalty": 0.0,
      "securityPenalty": 0.0,
      "errorPenalty": 0.0,
      "downAction": null,
      "rampTime": null,
      "port": null,
      "portType": null,
      "status": "online",
      "nodes": [
        {
          "id": 69,
          "name": "db-apache"
        },
        {
          "id": 74,
          "name": "bob-apache"
        }
      ],
      "monitors": [
        {
          "id": 64,
          "name": "bob-test"
        },
        {
          "id": 69,
          "name": "default-passive-lb-monitor"
        }
      ],
      "members": [

      ],
      "config": {
        "snatTranslationType": "LBSnatDisabled",
        "tcpMultiplexing": false,
        "tcpMultiplexingNumber": 6,
        "activeMonitorPaths": 64,
        "memberGroup": null,
        "passiveMonitorPath": 69
      },
      "createdBy": null,
      "dateCreated": "2021-10-19T17:39:34Z",
      "lastUpdated": "2021-12-02T18:08:36Z"
    },
    {
      "id": 114,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "dand-pool",
      "category": null,
      "visibility": "public",
      "description": "",
      "internalId": "/infra/lb-pools/816cd4be-36f8-4484-bc46-a17081b653b8",
      "externalId": "816cd4be-36f8-4484-bc46-a17081b653b8",
      "enabled": true,
      "vipSticky": null,
      "vipBalance": "ROUND_ROBIN",
      "allowNat": null,
      "allowSnat": null,
      "vipClientIpMode": null,
      "vipServerIpMode": null,
      "minActive": 1,
      "minInService": null,
      "minUpMonitor": null,
      "minUpAction": null,
      "maxQueueDepth": null,
      "maxQueueTime": null,
      "numberActive": 0,
      "numberInService": 0,
      "healthScore": 100.0,
      "performanceScore": 100.0,
      "healthPenalty": 0.0,
      "securityPenalty": 0.0,
      "errorPenalty": 0.0,
      "downAction": null,
      "rampTime": null,
      "port": null,
      "portType": null,
      "status": "online",
      "nodes": [

      ],
      "monitors": [
        {
          "id": 69,
          "name": "default-passive-lb-monitor"
        }
      ],
      "members": [

      ],
      "config": {
        "snatTranslationType": "LBSnatDisabled",
        "tcpMultiplexing": false,
        "tcpMultiplexingNumber": 6,
        "passiveMonitorPath": 69,
        "memberGroup": null
      },
      "createdBy": null,
      "dateCreated": "2021-11-01T21:25:08Z",
      "lastUpdated": "2021-12-02T18:08:36Z"
    },
    {
      "id": 64,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "ld-test-pools",
      "category": null,
      "visibility": "public",
      "description": "",
      "internalId": "/infra/lb-pools/fc03ef4b-f4b3-470c-8d03-025fe9a56f90",
      "externalId": "fc03ef4b-f4b3-470c-8d03-025fe9a56f90",
      "enabled": true,
      "vipSticky": null,
      "vipBalance": "ROUND_ROBIN",
      "allowNat": null,
      "allowSnat": null,
      "vipClientIpMode": null,
      "vipServerIpMode": null,
      "minActive": 1,
      "minInService": null,
      "minUpMonitor": null,
      "minUpAction": null,
      "maxQueueDepth": null,
      "maxQueueTime": null,
      "numberActive": 0,
      "numberInService": 0,
      "healthScore": 100.0,
      "performanceScore": 100.0,
      "healthPenalty": 0.0,
      "securityPenalty": 0.0,
      "errorPenalty": 0.0,
      "downAction": null,
      "rampTime": null,
      "port": null,
      "portType": null,
      "status": "online",
      "nodes": [

      ],
      "monitors": [

      ],
      "members": [

      ],
      "config": {
        "snatTranslationType": "LBSnatDisabled",
        "tcpMultiplexing": false,
        "tcpMultiplexingNumber": 6,
        "memberGroup": null
      },
      "createdBy": null,
      "dateCreated": "2021-10-19T17:39:34Z",
      "lastUpdated": "2021-12-02T18:08:36Z"
    },
    {
      "id": 128,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "Monitor HTTP 80",
      "category": null,
      "visibility": "public",
      "description": "",
      "internalId": "/infra/lb-pools/f38f4977-23d1-4f51-88c5-fd107d0a18b1",
      "externalId": "f38f4977-23d1-4f51-88c5-fd107d0a18b1",
      "enabled": true,
      "vipSticky": null,
      "vipBalance": "ROUND_ROBIN",
      "allowNat": null,
      "allowSnat": null,
      "vipClientIpMode": null,
      "vipServerIpMode": null,
      "minActive": 2,
      "minInService": null,
      "minUpMonitor": null,
      "minUpAction": null,
      "maxQueueDepth": null,
      "maxQueueTime": null,
      "numberActive": 0,
      "numberInService": 0,
      "healthScore": 100.0,
      "performanceScore": 100.0,
      "healthPenalty": 0.0,
      "securityPenalty": 0.0,
      "errorPenalty": 0.0,
      "downAction": null,
      "rampTime": null,
      "port": null,
      "portType": null,
      "status": "online",
      "nodes": [

      ],
      "monitors": [
        {
          "id": 79,
          "name": "dd-http-80-mon"
        }
      ],
      "members": [

      ],
      "config": {
        "snatTranslationType": "LBSnatDisabled",
        "tcpMultiplexing": false,
        "tcpMultiplexingNumber": 6,
        "activeMonitorPaths": 79,
        "memberGroup": null
      },
      "createdBy": null,
      "dateCreated": "2021-11-08T14:07:13Z",
      "lastUpdated": "2021-12-02T18:08:36Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 4,
    "total": 4
  }
}

This endpoint retrieves all load balancer pools associated with a specified load balancer.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/pools

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
name If specified will return an exact match on name
phrase If specified will return a partial match on name or description

Get a Specific Load Balancer Pool

curl "$serverUrl/api/load-balancers/80/pools/63" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "loadBalancerPool": {
    "id": 63,
    "loadBalancer": {
      "id": 80,
      "type": {
        "id": 19,
        "code": "nsx-t",
        "name": "NSX-T"
      },
      "name": "dand-nsxt",
      "ip": "10.32.23.7"
    },
    "name": "bob-test-pool",
    "category": null,
    "visibility": "public",
    "description": "",
    "internalId": "/infra/lb-pools/7d971e87-4e99-4a5a-a00f-0636f3431bdc",
    "externalId": "7d971e87-4e99-4a5a-a00f-0636f3431bdc",
    "enabled": true,
    "vipSticky": null,
    "vipBalance": "ROUND_ROBIN",
    "allowNat": null,
    "allowSnat": null,
    "vipClientIpMode": null,
    "vipServerIpMode": null,
    "minActive": 2,
    "minInService": null,
    "minUpMonitor": null,
    "minUpAction": null,
    "maxQueueDepth": null,
    "maxQueueTime": null,
    "numberActive": 0,
    "numberInService": 0,
    "healthScore": 100.0,
    "performanceScore": 100.0,
    "healthPenalty": 0.0,
    "securityPenalty": 0.0,
    "errorPenalty": 0.0,
    "downAction": null,
    "rampTime": null,
    "port": null,
    "portType": null,
    "status": "online",
    "nodes": [
      {
        "id": 69,
        "name": "db-apache"
      },
      {
        "id": 74,
        "name": "bob-apache"
      }
    ],
    "monitors": [
      {
        "id": 64,
        "name": "bob-test"
      },
      {
        "id": 69,
        "name": "default-passive-lb-monitor"
      }
    ],
    "members": [

    ],
    "config": {
      "snatTranslationType": "LBSnatDisabled",
      "tcpMultiplexing": false,
      "tcpMultiplexingNumber": 6,
      "activeMonitorPaths": 64,
      "memberGroup": null,
      "passiveMonitorPath": 69
    },
    "createdBy": null,
    "dateCreated": "2021-10-19T17:39:34Z",
    "lastUpdated": "2021-12-02T18:08:36Z"
  }
}

This endpoint retrieves a specific Load Balancer Pool.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/pools/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Pool to retrieve

Create a Load Balancer Pool

curl -XPOST "$serverUrl/api/load-balancers/:loadBalancerId/pools" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerPool": {
    "name": "test-pool",
    "description": "a test pool",
    "vipBalance": "ROUND_ROBIN",
    "minActive": 1,
    "config": {
      "snatTranslationType": "LBSnatDisabled",
      "tcpMultiplexing": true,
      "tcpMultiplexingNumber": 6
    }
  }
}'

The above command returns JSON structured like getting a single Load Balancer Pool:

Use this command to create a load balancer pool.

HTTP Request

POST $serverUrl/api/load-balancers/:loadBalancerId/pools

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

JSON Parameters

Parameter Default Description
name Name
description Description
vipBalance Balance Algorithm
minActive Min Active Members
config Configuration object with parameters that vary by type.

This endpoint allows creating a Load Balancer Pool. Configuration options vary by Load Balancer Type.

Update a Load Balancer Pool

curl -XPUT "$serverUrl/api/load-balancers/:loadBalancerId/pools/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerPool": {
    "description": "new description"
  }
}'

The above command returns JSON structured like getting a single Load Balancer Pool:

Use this command to update an existing load balancer pool.

HTTP Request

PUT $serverUrl/api/load-balancers/:loadBalancerId/pools/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Pool

JSON Parameters

Parameter Default Description
name Name
description Description
vipBalance Balance Algorithm
minActive Min Active Members
config Configuration object with parameters that vary by type.

This endpoint allows updating a Load Balancer Pool. Configuration options vary by Load Balancer Type.

Delete a Load Balancer Pool

curl -XDELETE "$serverUrl/api/load-balancers/:loadBalancerId/pools/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Load Balancer Pool from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/load-balancers/:loadBalancerId/pools/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Pool

Load Balancer Profiles

Provides API for managing Load Balancer Profiles.

Get All Load Balancer Profiles For Load Balancer

curl "$serverUrl/api/load-balancers/:loadBalancerId/profiles"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "loadBalancerProfiles": [
    {
      "id": 160,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "bob-test",
      "category": "loadBalancer.nsxt.profile.ssl.applicationProfile",
      "serviceType": "LBHttpProfile",
      "serviceTypeDisplay": "HTTP",
      "visibility": "public",
      "description": "",
      "internalId": "/infra/lb-app-profiles/bob-test",
      "externalId": "bob-test",
      "proxyType": null,
      "redirectRewrite": null,
      "persistenceType": null,
      "sslEnabled": null,
      "sslCert": null,
      "accountCertificate": null,
      "enabled": true,
      "redirectUrl": null,
      "insertXforwardedFor": false,
      "persistenceCookieName": null,
      "persistenceExpiresIn": null,
      "editable": true,
      "config": {
        "tags": [

        ],
        "httpsRedirect": null,
        "httpIdleTimeout": 16,
        "ntlmAuthentication": false,
        "requestHeaderSize": 1024,
        "responseHeaderSize": 4096,
        "responseTimeout": 60,
        "xForwardedFor": "INSERT",
        "profileType": "application-profile",
        "resource_type": "LBHttpProfile"
      },
      "createdBy": null,
      "dateCreated": "2021-10-19T17:39:31Z",
      "lastUpdated": "2021-10-19T17:49:32Z"
    },
    {
      "id": 171,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "dd-test-ssl-cipher",
      "category": "loadBalancer.nsxt.profile.ssl.clientSslProfile",
      "serviceType": "LBClientSslProfile",
      "serviceTypeDisplay": "Client SSL Profile",
      "visibility": "public",
      "description": "",
      "internalId": "/infra/lb-client-ssl-profiles/acb68f77-6b77-4e82-acf9-3cca7aa6b81c",
      "externalId": "acb68f77-6b77-4e82-acf9-3cca7aa6b81c",
      "proxyType": null,
      "redirectRewrite": null,
      "persistenceType": null,
      "sslEnabled": null,
      "sslCert": null,
      "accountCertificate": null,
      "enabled": true,
      "redirectUrl": null,
      "insertXforwardedFor": false,
      "persistenceCookieName": null,
      "persistenceExpiresIn": null,
      "editable": true,
      "config": {
        "tags": [

        ],
        "sslSuite": "CUSTOM",
        "supportedSslCiphers": [
          "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA"
        ],
        "supportedSslProtocols": [
          "TLS_V1"
        ],
        "preferServerCipher": true,
        "sessionCache": true,
        "sessionCacheTimeout": 300,
        "profileType": "ssl-profile",
        "resource_type": "LBClientSslProfile"
      },
      "createdBy": null,
      "dateCreated": "2021-10-19T17:39:32Z",
      "lastUpdated": "2021-10-19T17:49:33Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all load balancer profiles associated with a specified load balancer.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/profiles

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
name If specified will return an exact match on name
phrase If specified will return a partial match on name or description

Get a Specific Load Balancer Profile

curl "$serverUrl/api/load-balancers/80/profiles/63" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "loadBalancerProfile": {
    "id": 160,
    "loadBalancer": {
      "id": 80,
      "type": {
        "id": 19,
        "code": "nsx-t",
        "name": "NSX-T"
      },
      "name": "dand-nsxt",
      "ip": "10.32.23.7"
    },
    "name": "bob-test",
    "category": "loadBalancer.nsxt.profile.ssl.applicationProfile",
    "serviceType": "LBHttpProfile",
    "serviceTypeDisplay": "HTTP",
    "visibility": "public",
    "description": "",
    "internalId": "/infra/lb-app-profiles/bob-test",
    "externalId": "bob-test",
    "proxyType": null,
    "redirectRewrite": null,
    "persistenceType": null,
    "sslEnabled": null,
    "sslCert": null,
    "accountCertificate": null,
    "enabled": true,
    "redirectUrl": null,
    "insertXforwardedFor": false,
    "persistenceCookieName": null,
    "persistenceExpiresIn": null,
    "editable": true,
    "config": {
      "tags": [

      ],
      "httpsRedirect": null,
      "httpIdleTimeout": 16,
      "ntlmAuthentication": false,
      "requestHeaderSize": 1024,
      "responseHeaderSize": 4096,
      "responseTimeout": 60,
      "xForwardedFor": "INSERT",
      "profileType": "application-profile",
      "resource_type": "LBHttpProfile"
    },
    "createdBy": null,
    "dateCreated": "2021-10-19T17:39:31Z",
    "lastUpdated": "2021-10-19T17:49:32Z"
  }
}

This endpoint retrieves a specific Load Balancer Profile.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/profiles/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Profile to retrieve

Create a Load Balancer Profile

curl -XPOST "$serverUrl/api/load-balancers/:loadBalancerId/profiles" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerProfile": {
    "name": "test profile",
    "description": "a test profile",
    "serviceType": "LBHttpProfile",
    "config": {
      "profileType": "application-profile"
    }
  }
}'

The above command returns JSON structured like getting a single Load Balancer Profile:

Use this command to create a load balancer profile.

HTTP Request

POST $serverUrl/api/load-balancers/:loadBalancerId/profiles

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

JSON Parameters

Parameter Default Description
name Name
description Description
serviceType Service Type
config Configuration object with parameters that vary by type.

This endpoint allows creating a Load Balancer Profile. Configuration options vary by Load Balancer Type.

Update a Load Balancer Profile

curl -XPUT "$serverUrl/api/load-balancers/:loadBalancerId/profiles/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerProfile": {
    "description": "new description"
  }
}'

The above command returns JSON structured like getting a single Load Balancer Profile:

Use this command to update an existing load balancer profile.

HTTP Request

PUT $serverUrl/api/load-balancers/:loadBalancerId/profiles/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Profile

JSON Parameters

Parameter Default Description
name Name
description Description
config Configuration object with parameters that vary by type.

This endpoint allows updating a Load Balancer Profile. Configuration options vary by Load Balancer Type.

Delete a Load Balancer Profile

curl -XDELETE "$serverUrl/api/load-balancers/:loadBalancerId/profiles/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Load Balancer Profile from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/load-balancers/:loadBalancerId/profiles/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Profile

Load Balancer Monitors

Provides API for managing Load Balancer Monitors.

Get All Load Balancer Monitors For Load Balancer

curl "$serverUrl/api/load-balancers/:loadBalancerId/monitors"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "loadBalancerMonitors": [
    {
      "id": 64,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "bob-test",
      "code": null,
      "category": null,
      "visibility": "public",
      "description": "",
      "monitorType": "LBHttpMonitorProfile",
      "monitorInterval": 5,
      "monitorTimeout": 15,
      "sendData": null,
      "sendVersion": "HTTP_VERSION_1_1",
      "sendType": "GET",
      "receiveData": null,
      "receiveCode": "201",
      "disabledData": null,
      "monitorUsername": null,
      "monitorPassword": null,
      "monitorDestination": "/",
      "monitorReverse": false,
      "monitorTransparent": false,
      "monitorAdaptive": false,
      "aliasAddress": null,
      "aliasPort": 88,
      "internalId": "/infra/lb-monitor-profiles/8bb2ee52-d117-4f50-9b21-499e65545808",
      "externalId": "8bb2ee52-d117-4f50-9b21-499e65545808",
      "monitorSource": "external",
      "status": "ok",
      "statusMessage": null,
      "statusDate": null,
      "enabled": true,
      "maxRetry": 0,
      "fallCount": 3,
      "riseCount": 3,
      "dataLength": null,
      "config": {
      },
      "createdBy": null,
      "dateCreated": "2021-10-19T17:39:33Z",
      "lastUpdated": "2021-12-03T18:22:38Z"
    },
    {
      "id": 65,
      "loadBalancer": {
        "id": 80,
        "type": {
          "id": 19,
          "code": "nsx-t",
          "name": "NSX-T"
        },
        "name": "dand-nsxt",
        "ip": "10.32.23.7"
      },
      "name": "db-monitor-0526-1-new",
      "code": null,
      "category": null,
      "visibility": "public",
      "description": "My New Description",
      "monitorType": "LBHttpsMonitorProfile",
      "monitorInterval": 7,
      "monitorTimeout": 26,
      "sendData": "My new request body",
      "sendVersion": "HTTP_VERSION_1_0",
      "sendType": "GET",
      "receiveData": "My new response data",
      "receiveCode": "404",
      "disabledData": null,
      "monitorUsername": null,
      "monitorPassword": null,
      "monitorDestination": "http://facebook.com",
      "monitorReverse": false,
      "monitorTransparent": false,
      "monitorAdaptive": false,
      "aliasAddress": null,
      "aliasPort": 2,
      "internalId": "/infra/lb-monitor-profiles/efe8dc09-7f0f-4081-8797-4c2febecf074",
      "externalId": "efe8dc09-7f0f-4081-8797-4c2febecf074",
      "monitorSource": "external",
      "status": "ok",
      "statusMessage": null,
      "statusDate": null,
      "enabled": true,
      "maxRetry": 0,
      "fallCount": 5,
      "riseCount": 14,
      "dataLength": null,
      "config": {
      },
      "createdBy": null,
      "dateCreated": "2021-10-19T17:39:33Z",
      "lastUpdated": "2021-10-19T17:39:33Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 2,
    "size": 2,
    "total": 8
  }
}

This endpoint retrieves all load balancer monitors associated with specified load balancer.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/monitors

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
name If specified will return an exact match on name
phrase If specified will return a partial match on name or description

Get a Specific Load Balancer Monitor

curl "$serverUrl/api/load-balancers/80/monitors/64" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "loadBalancerMonitor": {
    "id": 64,
    "loadBalancer": {
      "id": 80,
      "type": {
        "id": 19,
        "code": "nsx-t",
        "name": "NSX-T"
      },
      "name": "dand-nsxt",
      "ip": "10.32.23.7"
    },
    "name": "bob-test",
    "code": null,
    "category": null,
    "visibility": "public",
    "description": "",
    "monitorType": "LBHttpMonitorProfile",
    "monitorInterval": 5,
    "monitorTimeout": 15,
    "sendData": null,
    "sendVersion": "HTTP_VERSION_1_1",
    "sendType": "GET",
    "receiveData": null,
    "receiveCode": "201",
    "disabledData": null,
    "monitorUsername": null,
    "monitorPassword": null,
    "monitorDestination": "/",
    "monitorReverse": false,
    "monitorTransparent": false,
    "monitorAdaptive": false,
    "aliasAddress": null,
    "aliasPort": 88,
    "internalId": "/infra/lb-monitor-profiles/8bb2ee52-d117-4f50-9b21-499e65545808",
    "externalId": "8bb2ee52-d117-4f50-9b21-499e65545808",
    "monitorSource": "external",
    "status": "ok",
    "statusMessage": null,
    "statusDate": null,
    "enabled": true,
    "maxRetry": 0,
    "fallCount": 3,
    "riseCount": 3,
    "dataLength": null,
    "config": {
    },
    "createdBy": null,
    "dateCreated": "2021-10-19T17:39:33Z",
    "lastUpdated": "2021-12-03T18:22:38Z"
  }
}

This endpoint retrieves a specific Load Balancer Monitor.

HTTP Request

GET $serverUrl/api/load-balancers/:loadBalancerId/monitors/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Monitor to retrieve

Create a Load Balancer Monitor

curl -XPOST "$serverUrl/api/load-balancers/:loadBalancerId/monitors" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerMonitor": {
    "name": "test monitor",
    "description": "a test monitor",
    "monitorType": "LBHttpMonitorProfile",
    "monitorTimeout": 15
  }
}'

The above command returns JSON structured like getting a single Load Balancer Monitor

Use this command to create a load balancer monitor.

HTTP Request

POST $serverUrl/api/load-balancers/:loadBalancerId/monitors

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer

JSON Parameters

Parameter Default Description
name Name
description Description
config Configuration object with parameters that vary by type.

This endpoint allows creating a Load Balancer Monitor. Configuration options vary by Load Balancer Type.

Update a Load Balancer Monitor

curl -XPUT "$serverUrl/api/load-balancers/:loadBalancerId/monitors/:id" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "loadBalancerMonitor": {
    "description": "new description"
  }
}'

The above command returns JSON structured like getting a single Load Balancer Monitor:

Use this command to update an existing load balancer monitor.

HTTP Request

PUT $serverUrl/api/load-balancers/:loadBalancerId/monitors/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Monitor

JSON Parameters

Parameter Default Description
name Name
description Description
config Configuration object with parameters that vary by type.

This endpoint allows updating a Load Balancer Monitor. Configuration options vary by Load Balancer Type.

Delete a Load Balancer Monitor

curl -XDELETE "$serverUrl/api/load-balancers/:loadBalancerId/monitors/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Load Balancer Monitor from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/load-balancers/:loadBalancerId/monitors/:id

URL Parameters

Parameter Description
loadBalancerId The ID of the Load Balancer
ID The ID of the Load Balancer Monitor

Storage

The Storage API endpoints provide the management of Storage Buckets and File Shares, Storage Volumes, and Storage Servers.

Storage Buckets

Provides API interfaces for managing Storage Buckets and File Shares. This is the endpoint for managing both Storage Buckets (object stores) and File Shares.

Get All Storage Buckets

curl "$serverUrl/api/storage-buckets"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "storageBuckets": [
    {
      "id": 1,
      "name": "s3 test",
      "accountId": 1,
      "providerType": "s3",
      "config": {
        "accessKey": "G429AED2C4L5YZB7Q",
        "secretKey": "************",
        "endpoint": ""
      },
      "bucketName": "morpheus-s3-test",
      "readOnly": false,
      "defaultBackupTarget": false,
      "defaultDeploymentTarget": false,
      "defaultVirtualImageTarget": false,
      "copyToStore": true
    },
    {
      "id": 2,
      "name": "testdrive",
      "accountId": 1,
      "providerType": "local",
      "config": {
        "basePath": "/tmp/testdrive"
      },
      "bucketName": ".",
      "readOnly": false,
      "defaultBackupTarget": false,
      "defaultDeploymentTarget": false,
      "defaultVirtualImageTarget": false,
      "copyToStore": false
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all storage buckets associated with the account.

HTTP Request

GET $serverUrl/api/storage-buckets

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on name
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Storage Bucket

curl "$serverUrl/api/storage-buckets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "storageBucket": {
    "id": 1,
    "name": "s3 test",
    "accountId": 1,
    "providerType": "s3",
    "config": {
      "accessKey": "G429AED2C4L5YZB7Q",
      "secretKey": "************",
      "endpoint": ""
    },
    "bucketName": "morpheus-s3-test",
    "readOnly": false,
    "defaultBackupTarget": false,
    "defaultDeploymentTarget": false,
    "defaultVirtualImageTarget": false,
    "copyToStore": true,
    "retentionPolicyType": null,
    "retentionPolicyDays": null,
    "retentionProvider": null
  }
}

This endpoint retrieves a specific storage bucket.

HTTP Request

GET $serverUrl/api/storage-buckets/:id

URL Parameters

Parameter Description
ID The ID of the storage bucket to retrieve

Create a Storage Bucket

curl -XPOST "$serverUrl/api/storage-buckets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "storageBucket": {
    "name": "test-storage",
    "providerType": "local",
    "config": {
      "basePath": "/tmp/test-storage"
    },
    "defaultBackupTarget": false,
    "copyToStore": true,
    "defaultDeploymentTarget": false,
    "defaultVirtualImageTarget": false,
    "retentionPolicyType": null,
    "retentionPolicyDays": null,
    "retentionProvider": null
  }
}'

The above command returns JSON structured like getting a single storage bucket:

HTTP Request

POST $serverUrl/api/storage-buckets

JSON Parameters

Parameter Default Description
name A unique name scoped to your account for the storage bucket
providerType The type of storage bucket. [s3, azure, cifs, local, nfs, openstack, rackspace]
config A map of config values. The expected values vary by providerType.
bucketName The name of the bucket. Only applies to certain types eg. s3
createBucket false Create the bucket if it does not exist. Only applies to certain types eg. s3
defaultBackupTarget Default Backup Target
copyToStore Archive Snapshots
defaultDeploymentTarget Default Deployment Target
defaultVirtualImageTarget Default Virtual Image Store
retentionPolicyType Cleanup mode. backup - Move old files to a backup provider. delete - Delete old files. none (default) - Keep all files.
retentionPolicyDays The number of days old a file must be before it is deleted.
retentionProvider The backup Storage Bucket where old files are moved to.

Amazon S3 (s3)

Parameter Default Description
config.accessKey Access Key
config.secretKey Secret Key
bucketName Bucket Name
createBucket false Create the bucket if it does not exist
config.region Optional Amazon region if creating a new bucket
config.endpoint Optional endpoint URL if pointing to an object store other than amazon that mimics the Amazon S3 APIs.

Azure (azure) Parameters

Parameter Default Description
config.storageAccount Storage Account
config.storageKey Storage Key
bucketName Bucket Name
createBucket false Create the bucket if it does not exist

CIFS (cifs) Parameters

Parameter Default Description
config.host Host
config.username Username
config.password Password
bucketName Bucket Name

Local Storage (local) Parameters

Parameter Default Description
config.basePath Storage Path

NFSv3 (nfs) Parameters

Parameter Default Description
config.host Host
config.exportFolder Export Folder
bucketName Bucket Name

Openstack Swift (openstack) Parameters

Parameter Default Description
config.username Username
config.apiKey API Key
config.region Region
bucketName Bucket Name
createBucket false Create the bucket if it does not exist
config.identityUrl Identity URL

Rackspace CDN (rackspace) Parameters

Parameter Default Description
config.username Username
config.apiKey API Key
config.region Region
bucketName Bucket Name
createBucket false Create the bucket if it does not exist

Update a Storage Bucket

curl -XPUT "$serverUrl/api/storage-buckets/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "storageBucket": {
    "name": "my-storage",
    "copyToStore": true
  }
}'

The above command returns JSON structured like getting a single storage bucket:

HTTP Request

PUT $serverUrl/api/storage-buckets/1

JSON Parameters

See Create.

Delete a Storage Bucket

curl -XDELETE "$serverUrl/api/storage-buckets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a storage bucket from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/storage-buckets/:id

URL Parameters

Parameter Description
ID The ID of the storage bucket

Storage Volumes

Provides API for managing Storage Volumes.

Get All Storage Volumes

curl "$serverUrl/api/storage-volumes"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "storageVolumes": [
    {
      "id": 161073,
      "name": "data",
      "description": null,
      "controllerId": 453611,
      "controllerMountPoint": "453611:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sda",
      "deviceDisplayName": "sda",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 214748364800,
      "displayOrder": 0,
      "maxIOPS": null,
      "uuid": null,
      "active": true,
      "zone": {
        "id": 29,
        "name": "den-vcenter"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": "den-vcenter",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 161339,
      "name": "data",
      "description": null,
      "controllerId": 454082,
      "controllerMountPoint": "454082:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sda",
      "deviceDisplayName": "sda",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 193273528320,
      "displayOrder": 0,
      "maxIOPS": null,
      "uuid": null,
      "active": true,
      "zone": {
        "id": 34,
        "name": "vmware"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": "vmware",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 161086,
      "name": "data",
      "description": null,
      "controllerId": 453647,
      "controllerMountPoint": "453647:0:6:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sda",
      "deviceDisplayName": "sda",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 107374182400,
      "displayOrder": 0,
      "maxIOPS": null,
      "uuid": null,
      "active": true,
      "zone": {
        "id": 29,
        "name": "den-vcenter"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": "den-vcenter",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 168510,
      "name": "data",
      "description": null,
      "controllerId": 461271,
      "controllerMountPoint": "461271:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sdb",
      "deviceDisplayName": "sdb",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 4294967296,
      "displayOrder": 1,
      "maxIOPS": null,
      "uuid": "4dfd4eba-4993-460a-ab7f-d48c51f2771e",
      "active": true,
      "zone": {
        "id": 34,
        "name": "vmware"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": " on ",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 161093,
      "name": "data",
      "description": null,
      "controllerId": 453665,
      "controllerMountPoint": "453665:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sda",
      "deviceDisplayName": "sda",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 4294967296,
      "displayOrder": 0,
      "maxIOPS": null,
      "uuid": null,
      "active": true,
      "zone": {
        "id": 29,
        "name": "den-vcenter"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": " on ",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 169806,
      "name": "data",
      "description": null,
      "controllerId": null,
      "controllerMountPoint": null,
      "resizeable": true,
      "rootVolume": true,
      "unitNumber": null,
      "deviceName": "/dev/sda1",
      "deviceDisplayName": "xvda",
      "type": {
        "id": 5,
        "code": "amazon-gp2",
        "name": "gp2"
      },
      "typeId": 5,
      "status": "attached",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 10737418240,
      "displayOrder": 0,
      "maxIOPS": null,
      "uuid": "47c1fcc5-0e9c-49ab-acef-1e343c83634f",
      "active": true,
      "zone": {
        "id": 39,
        "name": "qa-amazon2"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": "qa-amazon2",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 169807,
      "name": "data",
      "description": null,
      "controllerId": null,
      "controllerMountPoint": null,
      "resizeable": true,
      "rootVolume": true,
      "unitNumber": null,
      "deviceName": "/dev/xvda",
      "deviceDisplayName": "xvda",
      "type": {
        "id": 5,
        "code": "amazon-gp2",
        "name": "gp2"
      },
      "typeId": 5,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 10737418240,
      "displayOrder": 0,
      "maxIOPS": null,
      "uuid": "fb118f47-6e5b-4ca8-ae2c-31b2548dcf25",
      "active": true,
      "zone": {
        "id": 39,
        "name": "qa-amazon2"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": "qa-amazon2",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 206678,
      "name": "data",
      "description": null,
      "controllerId": 468113,
      "controllerMountPoint": "468113:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sdb",
      "deviceDisplayName": "sdb",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 10737418240,
      "displayOrder": 1,
      "maxIOPS": null,
      "uuid": "43deab59-ebd2-4984-a907-482c463474f6",
      "active": true,
      "zone": {
        "id": 34,
        "name": "vmware"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": " on ",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 207466,
      "name": "data",
      "description": null,
      "controllerId": 468224,
      "controllerMountPoint": "468224:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sdb",
      "deviceDisplayName": "sdb",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 10737418240,
      "displayOrder": 1,
      "maxIOPS": null,
      "uuid": "1d04f10d-4a9d-451d-b18e-f5105cf6cd5a",
      "active": true,
      "zone": {
        "id": 34,
        "name": "vmware"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": " on ",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 207482,
      "name": "data",
      "description": null,
      "controllerId": 468245,
      "controllerMountPoint": "468245:0:4:1",
      "resizeable": true,
      "rootVolume": false,
      "unitNumber": "1",
      "deviceName": "/dev/sdb",
      "deviceDisplayName": "sdb",
      "type": {
        "id": 1,
        "code": "standard",
        "name": "Disk"
      },
      "typeId": 1,
      "status": "provisioned",
      "statusMessage": null,
      "configurableIOPS": false,
      "maxStorage": 10737418240,
      "displayOrder": 1,
      "maxIOPS": null,
      "uuid": "c89ed79c-b4f4-4bcc-a123-fff4a38303c7",
      "active": true,
      "zone": {
        "id": 34,
        "name": "vmware"
      },
      "zoneId": null,
      "datastore": null,
      "datastoreId": null,
      "storageGroup": null,
      "storageServer": null,
      "source": " on ",
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 25,
    "total": 9387
  }
}

This endpoint retrieves all storage volumes associated with the account.

HTTP Request

GET $serverUrl/api/storage-volumes

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on name
name If specified will return an exact match on name

Get a Specific Storage Volume

curl "$serverUrl/api/storage-volumes/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "storageVolume": {
    "id": 207482,
    "name": "data",
    "description": null,
    "controllerId": 468245,
    "controllerMountPoint": "468245:0:4:1",
    "resizeable": true,
    "rootVolume": false,
    "unitNumber": "1",
    "deviceName": "/dev/sdb",
    "deviceDisplayName": "sdb",
    "type": {
      "id": 1,
      "code": "standard",
      "name": "Disk"
    },
    "typeId": 1,
    "status": "provisioned",
    "statusMessage": null,
    "configurableIOPS": false,
    "maxStorage": 10737418240,
    "displayOrder": 1,
    "maxIOPS": null,
    "uuid": "c89ed79c-b4f4-4bcc-a123-fff4a38303c7",
    "active": true,
    "zone": {
      "id": 34,
      "name": "vmware"
    },
    "zoneId": null,
    "datastore": null,
    "datastoreId": null,
    "storageGroup": null,
    "storageServer": null,
    "source": " on ",
    "owner": {
      "id": 1,
      "name": "Morpheus Data"
    }
  }
}

This endpoint retrieves a specific Storage Volume.

HTTP Request

GET $serverUrl/api/storage-volumes/:id

URL Parameters

Parameter Description
ID The ID of the Storage Volume to retrieve

Create a Storage Volume

curl -XPOST "$serverUrl/api/storage-volumes" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "storageVolume": {
    "storageServer": {
      "id": 679
    },
    "storageGroup": {
      "id": 37
    },
    "type": "isilon",
    "name": "test-volume",
    "namespace": {
      "id": 19
    },
    "maxStorage": 214748364800
  }
}'

The above command returns JSON structured like getting a single Storage Volume:

HTTP Request

POST $serverUrl/api/storage-volumes

JSON Parameters

Parameter Default Description
storageServer.id Storage Server ID
storageGroup.id Storage Group ID
type Storage Type Code or ID
name Name
config Configuration object with parameters that vary by type.

This endpoint allows creating a Storage Volume. Only certain types of storage servers support creating and deleting storage volumes, such as 3Par and Isilon. Configuration options vary by Storage Volume Type.

Delete a Storage Volume

curl -XDELETE "$serverUrl/api/storage-volumes/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Storage Volume from the system and make it no longer usable. Only certain types support this action.

HTTP Request

DELETE $serverUrl/api/storage-volumes/:id

URL Parameters

Parameter Description
ID The ID of the Storage Volume

Storage Volume Types

Provides API for viewing Storage Volume Types and their configuration options.

Get All Storage Volume Types

curl "$serverUrl/api/storage-volume-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "storageVolumeTypes": [
    {
      "id": 16,
      "code": "vmware-scsi",
      "name": "SCSI",
      "description": "VMware - SCSI",
      "displayOrder": 1,
      "defaultType": true,
      "customLabel": true,
      "customSize": true,
      "customSizeOptions": null,
      "configurableIOPS": false,
      "hasDatastore": null,
      "category": null,
      "enabled": true,
      "optionTypes": [

      ]
    },
    {
      "id": 17,
      "code": "vmware-ide",
      "name": "IDE",
      "description": "VMware - IDE",
      "displayOrder": 2,
      "defaultType": false,
      "customLabel": true,
      "customSize": true,
      "customSizeOptions": null,
      "configurableIOPS": false,
      "hasDatastore": null,
      "category": null,
      "enabled": true,
      "optionTypes": [

      ]
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 25,
    "total": 61
  }
}

This endpoint retrieves all Storage Volume Types. The sample response has been abbreviated.

HTTP Request

GET $serverUrl/api/storage-volume-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on name or code or description
name If specified will return an exact match on name or code
code If specified will return an exact match on code

Get a Specific Storage Volume Type

curl "$serverUrl/api/storage-volume-types/73" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "storageVolumeType": {
    "id": 73,
    "code": "google-ssd",
    "name": "Google SSD persistent",
    "description": "Google - Standard SSD persistent",
    "displayOrder": 3,
    "defaultType": true,
    "customLabel": true,
    "customSize": true,
    "customSizeOptions": null,
    "configurableIOPS": false,
    "hasDatastore": true,
    "category": "volume",
    "enabled": true,
    "optionTypes": [

    ]
  }
}

This endpoint retrieves a specific Storage Volume Type.

HTTP Request

GET $serverUrl/api/storage-volume-types/:id

URL Parameters

Parameter Description
ID The ID of the Storage Volume Type to retrieve

Storage Servers

Provides API for managing Storage Servers.

Get All Storage Servers

curl "$serverUrl/api/storage-servers"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "storageServers": [
    {
      "id": 207,
      "name": "AWS Prod",
      "type": {
        "id": 5,
        "code": "amazons3",
        "name": "AWS S3"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": null,
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": null,
      "servicePassword": null,
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": "ComputeZone",
      "refId": 21917,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2020-05-08T03:04:19Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2020-05-08T03:04:17Z",
      "lastUpdated": "2020-05-08T03:04:19Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 6,
      "name": "Labs 3Par",
      "type": {
        "id": 1,
        "code": "3par",
        "name": "3Par"
      },
      "chassis": null,
      "visibility": "public",
      "description": "3Par",
      "internalId": null,
      "externalId": null,
      "serviceUrl": "http://serviceurl:port",
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "username",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2020-05-12T01:38:12Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2018-10-21T05:56:56Z",
      "lastUpdated": "2020-05-12T01:38:12Z",
      "enabled": true,
      "groups": [
        {
          "id": 8,
          "name": "SSD_r5"
        }
      ],
      "hostGroups": [
        {
          "id": 1,
          "name": "labs-prod-vmware"
        }
      ],
      "hosts": [
        {
          "id": 1,
          "name": "labs-esxi-184"
        },
        {
          "id": 3,
          "name": "labs-esxi-183"
        },
        {
          "id": 4,
          "name": "labs-esxi-185"
        },
        {
          "id": 10,
          "name": "labs-esxi-192"
        },
        {
          "id": 7,
          "name": "labs-esxi-191"
        }
      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 17,
      "name": "Labs Dell ECS",
      "type": {
        "id": 4,
        "code": "ecs",
        "name": "Dell EMC ECS"
      },
      "chassis": null,
      "visibility": "public",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "username",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2019-06-07T04:22:00Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2019-04-01T22:36:50Z",
      "lastUpdated": "2019-06-07T04:22:00Z",
      "enabled": true,
      "groups": [
        {
          "id": 19,
          "name": "rg1"
        }
      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 7,
      "name": "Labs Dell Isilon",
      "type": {
        "id": 3,
        "code": "isilon",
        "name": "Dell EMC Isilon"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": "/",
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "username",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
        "storageGroup": "admin",
        "storageUser": "admin",
        "permissions": [
          "10.30.21.130",
          "10.30.21.120"
        ],
        "readPermissions": [
          "10.30.21.130",
          "10.30.21.120"
        ],
        "adminPermissions": [
          "10.30.21.130",
          "10.30.21.120"
        ]
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2021-11-11T22:24:07Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2018-10-23T03:44:36Z",
      "lastUpdated": "2021-11-11T22:24:07Z",
      "enabled": true,
      "groups": [
        {
          "id": 10,
          "name": "System"
        }
      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 769,
      "name": "Labs Dell Isilon H5",
      "type": {
        "id": 3,
        "code": "isilon",
        "name": "Dell EMC Isilon"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": "/",
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "username",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
        "storageGroup": null,
        "adminPermissions": [
          "10.30.21.120",
          "10.30.21.130"
        ],
        "permissions": [
          "10.30.21.120",
          "10.30.21.130"
        ],
        "storageUser": null,
        "readPermissions": [
          "10.30.21.120",
          "10.30.21.130"
        ]
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2021-10-29T00:02:53Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2021-08-31T20:35:46Z",
      "lastUpdated": "2021-10-29T00:02:53Z",
      "enabled": true,
      "groups": [
        {
          "id": 36,
          "name": "System"
        }
      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 584,
      "name": "Labs Google",
      "type": {
        "id": 13,
        "code": "google",
        "name": "Google Cloud Storage"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": null,
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "service-user@project.iam.gserviceaccount.com",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
        "projectId": "all"
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2021-05-27T23:18:10Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2021-05-27T23:18:08Z",
      "lastUpdated": "2021-05-27T23:18:53Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 555,
      "name": "Labs Huawei OBS",
      "type": {
        "id": 7,
        "code": "huaweiObs",
        "name": "Huawei OBS"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "username",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2021-01-05T18:05:08Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2021-01-05T18:05:08Z",
      "lastUpdated": "2021-01-05T18:05:08Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 554,
      "name": "Labs Huawei SFS",
      "type": {
        "id": 11,
        "code": "huaweiSFS",
        "name": "Huawei SFS"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": null,
      "servicePassword": null,
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
        "availabilityZone": "",
        "storageShareApiMicroVersion": "2.42"
      },
      "refType": "ComputeZone",
      "refId": 24812,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": null,
      "statusMessage": null,
      "statusDate": null,
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2021-01-05T18:04:43Z",
      "lastUpdated": "2021-01-05T18:04:45Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 73,
      "name": "Labs Open Telekom OBS",
      "type": {
        "id": 8,
        "code": "opentelekomObs",
        "name": "Open Telekom OBS"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": "username",
      "servicePassword": "************",
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": null,
      "refId": null,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2019-10-28T15:54:31Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2019-10-28T15:54:29Z",
      "lastUpdated": "2021-06-09T16:00:21Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 62,
      "name": "Labs Open Telekom SFS",
      "type": {
        "id": 10,
        "code": "opentelekomSFS",
        "name": "Open Telekom SFS"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": "https://serviceurl:port",
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": null,
      "servicePassword": null,
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
        "availabilityZone": "",
        "storageShareApiMicroVersion": "2.42"
      },
      "refType": "ComputeZone",
      "refId": 18988,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": null,
      "statusMessage": null,
      "statusDate": null,
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2019-10-25T19:48:57Z",
      "lastUpdated": "2021-12-04T21:12:54Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [
        {
          "id": 1,
          "name": "Morpheus Data"
        }
      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 384,
      "name": "MXQ946014H, bay 11",
      "type": {
        "id": 2,
        "code": "hpDriveEnclosure",
        "name": "HP Drive Enclosure"
      },
      "chassis": {
        "id": 67,
        "code": "oneview.enclosure.23875.797740MXQ946014H",
        "name": "MXQ946014H"
      },
      "visibility": "private",
      "description": "",
      "internalId": null,
      "externalId": "/rest/drive-enclosures/CN794100DQ",
      "serviceUrl": null,
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": null,
      "servicePassword": null,
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": "ComputeZone",
      "refId": 23875,
      "category": "oneview.driveEnclosure.23875",
      "serverVendor": "HPE",
      "serverModel": "Synergy D3940 Storage Module",
      "serialNumber": "CN794100DQ",
      "status": "OK",
      "statusMessage": null,
      "statusDate": "2020-10-21T16:44:16Z",
      "errorMessage": null,
      "maxStorage": 20615843020800,
      "usedStorage": null,
      "diskCount": 40,
      "dateCreated": "2020-10-21T16:44:16Z",
      "lastUpdated": "2021-08-01T20:15:05Z",
      "enabled": true,
      "groups": [
        {
          "id": 33,
          "name": "MXQ946014H disks"
        }
      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 13,
      "name": "Labs Amazon",
      "type": {
        "id": 5,
        "code": "amazons3",
        "name": "AWS S3"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": null,
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": null,
      "servicePassword": null,
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": "ComputeZone",
      "refId": 3,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2019-03-05T22:31:14Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2019-03-05T22:31:14Z",
      "lastUpdated": "2019-03-05T22:31:14Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    },
    {
      "id": 587,
      "name": "Labs Google",
      "type": {
        "id": 13,
        "code": "google",
        "name": "Google Cloud Storage"
      },
      "chassis": null,
      "visibility": "private",
      "description": null,
      "internalId": null,
      "externalId": null,
      "serviceUrl": null,
      "serviceHost": null,
      "servicePath": null,
      "serviceToken": null,
      "serviceVersion": null,
      "serviceUsername": null,
      "servicePassword": null,
      "internalIp": null,
      "externalIp": null,
      "apiPort": null,
      "adminPort": null,
      "config": {
      },
      "refType": "ComputeZone",
      "refId": 24935,
      "category": null,
      "serverVendor": null,
      "serverModel": null,
      "serialNumber": null,
      "status": "ok",
      "statusMessage": null,
      "statusDate": "2021-05-27T23:33:26Z",
      "errorMessage": null,
      "maxStorage": null,
      "usedStorage": null,
      "diskCount": null,
      "dateCreated": "2021-05-27T23:33:24Z",
      "lastUpdated": "2021-05-27T23:33:26Z",
      "enabled": true,
      "groups": [

      ],
      "hostGroups": [

      ],
      "hosts": [

      ],
      "tenants": [

      ],
      "owner": {
        "id": 1,
        "name": "Morpheus Data"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 14,
    "total": 14
  }
}

This endpoint retrieves all storage servers associated with the account.

HTTP Request

GET $serverUrl/api/storage-servers

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on name or description
name If specified will return an exact match on name

Get a Specific Storage Server

curl "$serverUrl/api/storage-servers/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "storageServer": {
    "id": 7,
    "name": "Labs Dell Isilon",
    "type": {
      "id": 3,
      "code": "isilon",
      "name": "Dell EMC Isilon"
    },
    "chassis": null,
    "visibility": "private",
    "description": null,
    "internalId": null,
    "externalId": null,
    "serviceUrl": "https://serviceurl:port",
    "serviceHost": null,
    "servicePath": "/",
    "serviceToken": null,
    "serviceVersion": null,
    "serviceUsername": "username",
    "servicePassword": "************",
    "internalIp": null,
    "externalIp": null,
    "apiPort": null,
    "adminPort": null,
    "config": {
      "storageGroup": "admin",
      "storageUser": "admin",
      "permissions": [
        "10.30.21.130",
        "10.30.21.120"
      ],
      "readPermissions": [
        "10.30.21.130",
        "10.30.21.120"
      ],
      "adminPermissions": [
        "10.30.21.130",
        "10.30.21.120"
      ]
    },
    "refType": null,
    "refId": null,
    "category": null,
    "serverVendor": null,
    "serverModel": null,
    "serialNumber": null,
    "status": "ok",
    "statusMessage": null,
    "statusDate": "2021-11-11T22:24:07Z",
    "errorMessage": null,
    "maxStorage": null,
    "usedStorage": null,
    "diskCount": null,
    "dateCreated": "2018-10-23T03:44:36Z",
    "lastUpdated": "2021-11-11T22:24:07Z",
    "enabled": true,
    "groups": [
      {
        "id": 10,
        "name": "System"
      }
    ],
    "hostGroups": [

    ],
    "hosts": [

    ],
    "tenants": [

    ],
    "owner": {
      "id": 1,
      "name": "Morpheus Data"
    }
  }
}

This endpoint retrieves a specific Storage Server.

HTTP Request

GET $serverUrl/api/storage-servers/:id

URL Parameters

Parameter Description
ID The ID of the Storage Server to retrieve

Create a Storage Server

curl -XPOST "$serverUrl/api/storage-servers" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "storageServer": {
    "type": "amazons3",
    "name": "testbucket",
    "description": "A test bucket",
    "enabled": true,
    "serviceUsername": "access-key",
    "servicePassword": "secret-key",
    "tenants": [
      {
        "id": 1
      }
    ],
    "visibility": "private"
  }
}'

The above command returns JSON structured like getting a single Storage Server:

HTTP Request

POST $serverUrl/api/storage-servers

JSON Parameters

Parameter Default Description
type Storage Type Code or ID
name Name
description Description
enabled true Enabled
config Configuration object with parameters that vary by type.
visibility private private or public
tenants Array of tenant account ids that are allowed access

This endpoint allows creating a Storage Server. Only certain types of clouds support creating and deleting storage servers. Configuration options vary by Storage Server Type.

Update a Storage Server

curl -XPUT "$serverUrl/api/storage-servers/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "storageServer": {
    "description": "a test s3 bucket"
  }
}'

The above command returns JSON structured like getting a single Storage Server:

HTTP Request

PUT $serverUrl/api/storage-servers/:id

URL Parameters

Parameter Description
ID The ID of the Storage Server

JSON Parameters

Parameter Default Description
name Name
description Description
enabled true Enabled
config Configuration object with parameters that vary by type.
visibility private private or public
tenants Array of tenant account ids that are allowed access

This endpoint allows updating a Storage Server. Configuration options vary by Storage Server Type.

Delete a Storage Server

curl -XDELETE "$serverUrl/api/storage-servers/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a Storage Server from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/storage-servers/:id

URL Parameters

Parameter Description
ID The ID of the Storage Server

Storage Server Types

Provides API for viewing Storage Server Types and their configuration options.

curl "$serverUrl/api/storage-server-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "storageServerTypes": [
    {
      "id": 1,
      "code": "3par",
      "name": "3Par",
      "description": "3Par",
      "enabled": true,
      "creatable": true,
      "hasNamespaces": false,
      "hasGroups": true,
      "hasBlock": true,
      "hasObject": false,
      "hasFile": false,
      "hasDatastore": true,
      "hasDisks": false,
      "hasHosts": true,
      "createNamespaces": false,
      "createGroup": false,
      "createBlock": true,
      "createObject": false,
      "createFile": false,
      "createDatastore": true,
      "createDisk": false,
      "createHost": false,
      "iconCode": null,
      "hasFileBrowser": true,
      "optionTypes": [

      ],
      "groupOptionTypes": [

      ],
      "bucketOptionTypes": [

      ],
      "shareOptionTypes": [

      ],
      "shareAccessOptionTypes": [

      ],
      "storageVolumeTypes": [
        {
          "id": 15,
          "code": "3par",
          "name": "3Par Volume",
          "displayOrder": 1,
          "defaultType": true,
          "customLabel": false,
          "customSize": false,
          "customSizeOptions": null
        }
      ]
    },
    {
      "id": 6,
      "code": "amazonefs",
      "name": "AWS EFS",
      "description": "Amazon Elastic Files Services",
      "enabled": true,
      "creatable": false,
      "hasNamespaces": false,
      "hasGroups": false,
      "hasBlock": false,
      "hasObject": false,
      "hasFile": true,
      "hasDatastore": false,
      "hasDisks": true,
      "hasHosts": false,
      "createNamespaces": false,
      "createGroup": false,
      "createBlock": false,
      "createObject": false,
      "createFile": true,
      "createDatastore": true,
      "createDisk": false,
      "createHost": false,
      "iconCode": null,
      "hasFileBrowser": true,
      "optionTypes": [

      ],
      "groupOptionTypes": [

      ],
      "bucketOptionTypes": [

      ],
      "shareOptionTypes": [

      ],
      "shareAccessOptionTypes": [

      ],
      "storageVolumeTypes": [
        {
          "id": 30,
          "code": "hpEnclosureDisk",
          "name": "HP Enclosure Disk",
          "displayOrder": 1,
          "defaultType": true,
          "customLabel": false,
          "customSize": false,
          "customSizeOptions": null
        }
      ]
    },
    {
      "id": 5,
      "code": "amazons3",
      "name": "AWS S3",
      "description": "Amazon S3 Services",
      "enabled": true,
      "creatable": true,
      "hasNamespaces": false,
      "hasGroups": false,
      "hasBlock": false,
      "hasObject": true,
      "hasFile": false,
      "hasDatastore": false,
      "hasDisks": true,
      "hasHosts": false,
      "createNamespaces": false,
      "createGroup": false,
      "createBlock": false,
      "createObject": true,
      "createFile": false,
      "createDatastore": true,
      "createDisk": false,
      "createHost": false,
      "iconCode": null,
      "hasFileBrowser": true,
      "optionTypes": [

      ],
      "groupOptionTypes": [

      ],
      "bucketOptionTypes": [

      ],
      "shareOptionTypes": [

      ],
      "shareAccessOptionTypes": [

      ],
      "storageVolumeTypes": [
        {
          "id": 48,
          "code": "s3Object",
          "name": "AWS S3 Object Storage",
          "displayOrder": 1,
          "defaultType": true,
          "customLabel": true,
          "customSize": true,
          "customSizeOptions": null
        }
      ]
    },
    {
      "id": 4,
      "code": "ecs",
      "name": "Dell EMC ECS",
      "description": "Dell EMC ECS",
      "enabled": true,
      "creatable": true,
      "hasNamespaces": true,
      "hasGroups": true,
      "hasBlock": false,
      "hasObject": true,
      "hasFile": true,
      "hasDatastore": false,
      "hasDisks": false,
      "hasHosts": false,
      "createNamespaces": false,
      "createGroup": false,
      "createBlock": false,
      "createObject": true,
      "createFile": true,
      "createDatastore": false,
      "createDisk": false,
      "createHost": false,
      "iconCode": null,
      "hasFileBrowser": true,
      "optionTypes": [

      ],
      "groupOptionTypes": [

      ],
      "bucketOptionTypes": [

      ],
      "shareOptionTypes": [

      ],
      "shareAccessOptionTypes": [

      ],
      "storageVolumeTypes": [
        {
          "id": 42,
          "code": "ecsBlock",
          "name": "ECS Block Storage",
          "displayOrder": 1,
          "defaultType": true,
          "customLabel": true,
          "customSize": true,
          "customSizeOptions": null
        },
        {
          "id": 41,
          "code": "ecsObject",
          "name": "ECS Object Storage",
          "displayOrder": 1,
          "defaultType": true,
          "customLabel": true,
          "customSize": true,
          "customSizeOptions": null
        },
        {
          "id": 43,
          "code": "ecsFileSystem",
          "name": "ECS Shared File System",
          "displayOrder": 1,
          "defaultType": true,
          "customLabel": true,
          "customSize": true,
          "customSizeOptions": null
        }
      ]
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 13,
    "total": 13
  }
}

This endpoint retrieves all Storage Server Types. The sample response has been abbreviated.

HTTP Request

GET $serverUrl/api/storage-server-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase If specified will return a partial match on name or code or description
name If specified will return an exact match on name or code
code If specified will return an exact match on code

Get a Specific Storage Server Type

curl "$serverUrl/api/storage-server-types/73" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "storageServerType": {
    "id": 5,
    "code": "amazons3",
    "name": "AWS S3",
    "description": "Amazon S3 Services",
    "enabled": true,
    "creatable": true,
    "hasNamespaces": false,
    "hasGroups": false,
    "hasBlock": false,
    "hasObject": true,
    "hasFile": false,
    "hasDatastore": false,
    "hasDisks": true,
    "hasHosts": false,
    "createNamespaces": false,
    "createGroup": false,
    "createBlock": false,
    "createObject": true,
    "createFile": false,
    "createDatastore": true,
    "createDisk": false,
    "createHost": false,
    "iconCode": null,
    "hasFileBrowser": true,
    "optionTypes": [
      {
        "id": 1016,
        "name": "serviceUsername",
        "description": null,
        "code": "storageServer.amazon.serviceUsername",
        "fieldName": "serviceUsername",
        "fieldLabel": "Access Key",
        "fieldCode": "gomorpheus.optiontype.AccessKey",
        "fieldContext": "storageServer",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "fieldInput": null,
        "placeHolder": null,
        "verifyPattern": null,
        "helpBlock": "",
        "helpBlockFieldCode": null,
        "defaultValue": null,
        "optionSource": null,
        "optionSourceType": null,
        "optionList": null,
        "type": "text",
        "advanced": false,
        "required": true,
        "exportMeta": false,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 10,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "visibleOnCode": null,
        "requireOnCode": null,
        "contextualDefault": false,
        "displayValueOnDetails": null,
        "showOnCreate": null,
        "showOnEdit": null
      },
      {
        "id": 1017,
        "name": "servicePassword",
        "description": null,
        "code": "storageServer.amazon.servicePassword",
        "fieldName": "servicePassword",
        "fieldLabel": "Secret Key",
        "fieldCode": "gomorpheus.optiontype.SecretKey",
        "fieldContext": "storageServer",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "fieldInput": null,
        "placeHolder": null,
        "verifyPattern": null,
        "helpBlock": "",
        "helpBlockFieldCode": null,
        "defaultValue": null,
        "optionSource": null,
        "optionSourceType": null,
        "optionList": null,
        "type": "password",
        "advanced": false,
        "required": true,
        "exportMeta": false,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 11,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "visibleOnCode": null,
        "requireOnCode": null,
        "contextualDefault": false,
        "displayValueOnDetails": null,
        "showOnCreate": null,
        "showOnEdit": null
      },
      {
        "id": 1018,
        "name": "serviceUrl",
        "description": null,
        "code": "storageServer.amazon.serviceUrl",
        "fieldName": "serviceUrl",
        "fieldLabel": "Endpoint",
        "fieldCode": "gomorpheus.optiontype.Endpoint",
        "fieldContext": "storageServer",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "fieldInput": null,
        "placeHolder": null,
        "verifyPattern": null,
        "helpBlock": "",
        "helpBlockFieldCode": null,
        "defaultValue": null,
        "optionSource": null,
        "optionSourceType": null,
        "optionList": null,
        "type": "text",
        "advanced": false,
        "required": false,
        "exportMeta": false,
        "editable": true,
        "creatable": true,
        "config": {
        },
        "displayOrder": 12,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "visibleOnCode": null,
        "requireOnCode": null,
        "contextualDefault": false,
        "displayValueOnDetails": null,
        "showOnCreate": null,
        "showOnEdit": null
      }
    ],
    "groupOptionTypes": [

    ],
    "bucketOptionTypes": [

    ],
    "shareOptionTypes": [

    ],
    "shareAccessOptionTypes": [

    ],
    "storageVolumeTypes": [
      {
        "id": 48,
        "code": "s3Object",
        "name": "AWS S3 Object Storage",
        "displayOrder": 1,
        "defaultType": true,
        "customLabel": true,
        "customSize": true,
        "customSizeOptions": null
      }
    ]
  }
}

This endpoint retrieves a specific Storage Server Type.

HTTP Request

GET $serverUrl/api/storage-server-types/:id

URL Parameters

Parameter Description
ID The ID of the Storage Server Type to retrieve

Key Pairs

Morpheus provides a database for keeping track of Key Pairs in the system. These can be used for provisioning servers and auto assigning added keypairs.

curl "$serverUrl/api/key-pairs"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "keyPairCount": 1,
  "keyPairs": [
    {
      "accountId": 1,
      "id": 2,
      "name": "Test",
      "privateKey": null,
      "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDXhVj5Oe88bXPmNA32iZ0ijlgbTkeCgnTkLwDyGfOTBH56QR9gwU66B1mh+ceU/lm1jS0zNuHtGFiMabbL+7a+MgJ7HVuaV4CR2/a/cp1yEzvvuJE6IvoGzDiXIdafasdfxcvdfadfvcEyOn+TW16rbS6GR/IwuvS81GqSJ6Z5/IJh4R5IW5yzK6z6BTHtX+vQQN9xv60JmwBC1NO5UVps2KVDBSCildlNlPR4AFrtVYDPSjRmjvj3DjGnJ6YlgjFIgc23bk1t0pknocgkB+7QZrkt1ed6AWVojGTUo2B9Cd/MphCKfZ mykey"
    }
  ],
  "success": true
}

This endpoint retrieves all key pairs associated with the account.

HTTP Request

GET $serverUrl/api/key-pairs

Query Parameters

Parameter Default Description
lastUpdated A date filter, restricts query to only load keypairs updated more recent or equal to the date specified
name If specified will return an exact match keypair

Get a Specific Key Pair

curl "$serverUrl/api/key-pairs/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "keyPair": {
    "accountId": 1,
    "id": 2,
    "name": "Test",
    "privateKey": null,
    "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDXhVj5Oe88bXPmNA32iZ0ijlgbTkeCgnTkLwDyGfOTBH56QR9gwU66B1mh+ceU/lm1jS0zNuHtGFiMabbL+7a+MgJ7HVuaV4CR2/a/cp1yEzvvuJE6IvoGzDiXIdafasdfxcvdfadfvcEyOn+TW16rbS6GR/IwuvS81GqSJ6Z5/IJh4R5IW5yzK6z6BTHtX+vQQN9xv60JmwBC1NO5UVps2KVDBSCildlNlPR4AFrtVYDPSjRmjvj3DjGnJ6YlgjFIgc23bk1t0pknocgkB+7QZrkt1ed6AWVojGTUo2B9Cd/MphCKfZ mykey"
  },
  "success": true
}

This endpoint retrieves a specific key.

HTTP Request

GET $serverUrl/api/key-pairs/:id

URL Parameters

Parameter Description
ID The ID of the key pair

Create a KeyPair

curl -XPOST "$serverUrl/api/key-pairs" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"keyPair":{
    "name": "My Key",
    "publicKey": "ssh-rsa",
    "privateKey": "privateKey Optional for most cases"
  }}'

The above command returns JSON structured like getting a single keyPair:

HTTP Request

POST $serverUrl/api/key-pairs

JSON Key Pair Parameters

Parameter Default Description
name A unique name scoped to your account for the key
publicKey The public key pair value
privateKey The private key pair value (optional)

NOTE The Public and Private key are stored in encrypted form in the database.

Delete a Key Pair

curl -XDELETE "$serverUrl/api/key-pairs/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a key pair from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/key-pairs/:id

URL Parameters

Parameter Description
ID The ID of the key pair

SSL Certificates

Morpheus provides a database for keeping track of SSL Certificates in the system. These can be applied to various load balancers within the system and instances that use them.

Get All SSL Certificates

curl "$serverUrl/api/certificates" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "certificateCount": 1,
  "certificates": [
    {
      "accountId": 1,
      "certFile": "certFileContent",
      "domainName": "test.local",
      "generated": false,
      "id": 1,
      "keyFile": "keyFileContent",
      "name": "Test Cert",
      "wildcard": true
    }
  ]
}

This endpoint retrieves all key pairs associated with the account.

HTTP Request

GET $serverUrl/api/certificates

Query Parameters

Parameter Default Description
name Filter on name

Get a Specific Certificate

curl "$serverUrl/api/certificates/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "certificate": {
    "accountId": 1,
    "certFile": "certFileContent",
    "domainName": "test.local",
    "generated": false,
    "id": 1,
    "keyFile": "keyFileContent",
    "name": "Test Cert",
    "wildcard": true
  },
  "succcess": true
}

This endpoint retrieves a specific key.

HTTP Request

GET $serverUrl/api/certificates/:id

URL Parameters

Parameter Description
ID The ID of the key pair to retrieve

Create a Certificate

curl -XPOST "$serverUrl/api/certificates" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"certificate":{
    "name": "My Cert",
    "certFile": "my cert file contents",
    "keyFile": "My keyfile",
    "domainName": "Domain name of cert",
    "wildcard": false
  }}'

The above command returns JSON structured like getting a single certificate:

HTTP Request

POST $serverUrl/api/certificates

JSON Certificate Parameters

Parameter Default Description
name A unique name scoped to your account for the key
certFile The contents of the certificate file
keyFile The contents of the key file
wildcard false Wether or not this certificate is a wildcard cert
domainName The domain name this certificate is tied to

Updating a Certificate

curl -XPUT "$serverUrl/api/certificates/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"certificate":{
    "name": "My Cert",
    "certFile": "my cert file contents",
    "keyFile": "My keyfile",
    "domainName": "Domain name of cert",
    "wildcard": false
  }}'

The above command returns JSON structured like getting a single certificate:

HTTP Request

PUT $serverUrl/api/certificates/:id

JSON Certificate Parameters

Parameter Default Description
name A unique name scoped to your account for the key
certFile The contents of the certificate file
keyFile The contents of the key file
wildcard false Wether or not this certificate is a wildcard cert
domainName The domain name this certificate is tied to

Delete a Certificate

curl -XDELETE "$serverUrl/api/certificates/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a certificate from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/certificates/:id

Logs

The Logs API allows fetching log records generated by your containers, hosts, and clusters.

Get All Logs

Fetch a paginated list of logs records. By default the most recent records are returned. Results may be scoped to specific containers, servers or a cluster.

curl "$serverUrl/api/logs"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "sort": {
    "ts": "desc"
  },
  "offset": 0,
  "start": "2019-10-18T01:04:55Z",
  "end": "2019-10-25T01:04:55Z",
  "data": [
    {
      "typeCode": "server",
      "level": "INFO",
      "sourceType": "sudo",
      "message": "  pam_unix(sudo:session): session closed for user root\n",
      "ts": "2019-10-25T00:57:46Z",
      "priority": 300,
      "hostname": "localhost",
      "objectId": "664",
      "seq": 5869011,
      "_id": "84781694-d7e8-463d-bb08-7f9e4022a1da"
    }
  ],
  "max": 25,
  "total": 32038,
  "success": true,
  "count": 25
}

HTTP Request

GET $serverUrl/api/logs

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort ts Sort order
order desc Sort direction
query Filter by wildcard search of fields
message Filter by message.
sourceType Filter by source type
typeCode Filter by source type
objectId Filter by objectId
token Filter by token
level Filter by log level. DEBUG, INFO, ERROR. Multiple values can be passed pipe delimited. Example: `WARN
startMs Date filter in milliseconds (unix epoch), restricts query to only load logs updated more recently than the time specified.
endMs Date filter in milliseconds (unix epoch), restricts query to only load logs updated before the time specified.
startDateTime Date filter in dateTime format yyyy-mm-ddTHH:mm:ssZ eg: 2023-01-02T13:24:00+03:00, restricts query to only load logs updated more recently than the date specified.
endDateTime Date filter in dateTime format yyyy-mm-ddTHH:mm:ssZ eg: 2023-06-30T02:24:00-01:00, restricts query to only load logs updated before the date specified.
containers Filter by Container ID. Accepts multiple values.
servers Filter by Server ID. Accepts multiple values.
clusterId Filter by Cluster ID

Response

Name Description
sort The returned sort order.
offset The returned offset value.
max The returned max value
size The number of records returned.
total The total number of records found.
data Array of log record objects.

Log Record Object

Name Description
typeCode Log Type Code. Example: “server”
level Log Source type. Example: “sudo”
sourceType Log Source type. Example: “sudo”
message Log message
ts Log timestamp Example: “2019-10-25T01:04:46Z”
hostname Hostname.
priority Priority.
objectId Object ID
seq Log Sequence ID
_id A Unique ID for this log record.

Get Container Logs

Fetch a paginated list of logs, for specific containers only.

curl "$serverUrl/api/logs?containers=3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

The response is the same as Get All Logs.

Get Host Logs

Fetch a paginated list of logs, for specific hosts only.

curl "$serverUrl/api/logs?servers=3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

The response is the same as Get All Logs.

Get Cluster Logs

Fetch a paginated list of logs, for a specific cluster only.

curl "$serverUrl/api/logs?clusterId=5" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

The response is the same as Get All Logs.

Monitoring

The Monitoring API endpoints provide the management of monitoring Checks, Check Groups, Check Apps, Incidents, Contacts, and Alerts.

Monitor Apps

These entities define a collection of monitoring checks and/or check groups that are associated with a specific app.

curl "$serverUrl/api/monitoring/apps"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "monitorApps": [
    {
      "id": 82,
      "account": {
        "id": 1
      },
      "active": true,
      "app": {
        "id": 82,
        "name": "testnginx"
      },
      "name": "testnginx",
      "checks": [

      ],
      "checkGroups": [
        201
      ],
      "description": null,
      "inUptime": true,
      "lastCheckStatus": null,
      "lastWarningDate": null,
      "lastErrorDate": null,
      "lastSuccessDate": null,
      "lastRunDate": "2018-07-11T22:45:00+0000",
      "lastError": null,
      "lastTimer": 7,
      "health": 0,
      "history": null,
      "severity": "critical",
      "createIncident": true,

      "createdBy": {
        "id": 1,
        "username": "james"
      },
      "dateCreated": "2018-02-20T18:28:38+0000",
      "lastUpdated": "2018-07-11T22:45:00+0000",
      "availability": 99.45081019
    }
  ],
  "meta": {
    "size": 5,
    "total": 5,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all monitor apps.

HTTP Request

GET $serverUrl/api/monitoring/apps

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort health Sort order
name Filter by name
phrase Filter by wildcard search of name and description
status Filter by health status: error, healthy, warning, muted
lastUpdated Date filter, restricts query to only load checks updated timestamp is more recent or equal to the date specified
deleted false Pass true to see checks that have been deleted.

Get a Specific Monitor App

curl "$serverUrl/api/monitoring/apps/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "monitorApp": {
    "id": 82,
    "account": {
      "id": 1
    },
    "active": true,
    "app": {
      "id": 82,
      "name": "testnginx"
    },
    "name": "testnginx",
    "checks": [

    ],
    "checkGroups": [
      201
    ],
    "description": null,
    "inUptime": true,
    "lastCheckStatus": null,
    "lastWarningDate": null,
    "lastErrorDate": null,
    "lastSuccessDate": null,
    "lastRunDate": "2018-07-11T22:45:00+0000",
    "lastError": null,
    "lastTimer": 7,
    "health": 0,
    "history": null,
    "severity": "critical",
    "createIncident": true,
    "createdBy": {
      "id": 1,
      "username": "james"
    },
    "dateCreated": "2018-02-20T18:28:38+0000",
    "lastUpdated": "2018-07-11T22:45:00+0000",
    "availability": 99.45081019
  },
  "checkGroups": [
    {
      "id": 201,
      "account": {
        "id": 1
      },
      "instance": {
        "id": 293,
        "name": "testnginx-18"
      },
      "name": "testnginx-18",
      "description": null,
      "inUptime": true,
      "lastCheckStatus": null,
      "lastWarningDate": null,
      "lastErrorDate": null,
      "lastSuccessDate": null,
      "lastRunDate": "2018-07-11T22:45:00+0000",
      "lastError": null,
      "outageTime": 0,
      "lastTimer": 7,
      "health": 0,
      "history": null,
      "minHappy": 1,
      "lastMetric": null,
      "severity": "critical",
      "createIncident": true,
      "createdBy": {
        "id": 1,
        "username": "james"
      },
      "dateCreated": "2018-02-20T18:34:55+0000",
      "lastUpdated": "2018-07-11T22:45:00+0000",
      "availability": 99.45081019,
      "checkType": {
        "id": 1,
        "code": "webGetCheck",
        "name": "Web Check",
        "metricName": "response"
      }
    }
  ],
  "openIncidents": [
    {
      "id": 582,
      "account": {
        "id": 1
      },
      "app": {
        "id": 82,
        "name": "testnginx"
      },
      "autoClose": true,
      "channelId": "1543448c-e391-404c-81fb-4deedb079f32",
      "checkGroups": [
        {
          "id": 201,
          "name": "testnginx-18"
        }
      ],
      "checks": [

      ],
      "comment": null,
      "displayName": "testnginx-18",
      "duration": null,
      "endDate": null,
      "inUptime": true,
      "lastCheckTime": "2018-07-11T22:45:00+0000",
      "lastError": "unheard from beyond check interval limit.",
      "lastMessage": null,
      "name": "testnginx18",
      "resolution": null,
      "severity": "critical",
      "severityId": 20,
      "startDate": "2018-07-11T22:45:00+0000",
      "status": "open",
      "visibility": "private"
    }
  ]
}

This endpoint retrieves a specific monitor app.

HTTP Request

GET $serverUrl/api/monitoring/apps/:id

URL Parameters

Parameter Description
ID ID of the monitor app

Create a Monitor App

curl -XPOST "$serverUrl/api/monitoring/apps" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"monitorApp":{
    "name": "My App Checks",
    "checks": [1,2]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single contact

HTTP Request

POST $serverUrl/api/monitoring/apps

JSON Parameters

Parameter Default Description
name Unique name scoped to your account for the monitor app
description Optional description field
minHappy 1 Min Happy. This specifies the minimum number of checks within inUptime
active true Used to determine if monitor app is active
severity critical Severity level of incidents that are created when this check fails. They can be info, warning, or critical
checks Array of Check IDs
checkGroups Array of Check Group IDs

Updating a Monitor App

curl -XPUT "$serverUrl/api/monitoring/apps/3" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"monitorApp":{
    "checks": [],
    "checkGroups": [55]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single monitor app

HTTP Request

PUT $serverUrl/api/monitoring/apps/:id

URL Parameters

Parameter Description
ID ID of the monitor app

JSON Parameters

Parameter Default Description
name Unique name scoped to your account for the monitor app
description Description
minHappy Min Happy. This specifies the minimum number of checks within the app that must be happy to keep the app from becoming unhealthy.
severity Max Severity. Determines the maximum severity level this app can incur on an incident when failing. Default is critical
active true Used to determine if monitor app is active
inUptime Affects Availability. Default is on.
checks Array of Check IDs
checkGroups Array of Check Group IDs

Mute a Monitor App

curl -XPUT "$serverUrl/api/monitoring/apps/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": true
}

This endpoint can be used to toggle the mute state of a monitor app. This sets createIncident to the opposite of muted.

Unmute a Monitor App

curl -XPUT "$serverUrl/api/monitoring/apps/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false
}

The same endpoint is used to unmute by passing the parameter "muted":false.

HTTP Request

PUT $serverUrl/api/monitoring/checks/:id/mute

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

Mute All Monitor Apps

curl -XPUT "$serverUrl/api/monitoring/apps/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false,
  "updated": 3
}

HTTP Request

PUT $serverUrl/api/monitoring/apps/mute-all

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

This endpoint can be used to toggle the mute state of all monitor apps. This sets createIncident to the opposite of muted.

Unmute All Monitor App

curl -XPUT "$serverUrl/api/monitoring/apps/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false,
  "updated": 3
}

The same endpoint is used to unmute by passing the parameter "muted":false.

Delete a Monitor App

curl -XDELETE "$serverUrl/api/monitoring/apps/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/monitoring/apps/:id

URL Parameters

Parameter Description
ID ID of the monitor app

Checks

These entities define what and when a monitoring check is executed within the Morpheus system. Morpheus supports a vast array of different check types (not solely web checks). The API provides a means to list all of an account’s checks in addition to create, modify, mute, and or delete them.

Get All Checks

curl "$serverUrl/api/monitoring/checks" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "checks": [
    {
      "id": 798,
      "account": {
        "id": 1
      },
      "active": true,
      "apiKey": "03850a42-b97a-4426-8733-924b8cf6e262",
      "availability": 99.9804109,
      "checkAgent": null,
      "checkIntegrations": [

      ],
      "checkInterval": 300,
      "checkSpec": null,
      "checkType": {
        "id": 1
      },
      "config": {  "webMethod": "GET",  "webUrl": "http://google.com"},
      "createIncident": true,
      "dateCreated": "2015-05-16T12:05:23Z",
      "deleted": false,
      "description": null,
      "health": 10,
      "history": "{\"checkDates\":[1433339580607,1433339595119,1433339613169,1433339625412,1433339641010,1433339655209,1433339670178,1433339687802,1433339700471,1433339715171,1433339730710,1433339745351,1433339764299,1433339775508,1433339790377,1433339805373,1433339820944,1433339835996,1433339850317,1433339865833,1433339880884,1433339895489,1433339910554,1433339925660,1433339940875,1433339956143,1433339970551,1433339985179,1433340000961,1433340015765],\"successList\":[true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true],\"healthList\":[10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10],\"timerList\":[347,410,338,337,365,361,373,374,358,337,350,505,342,338,358,359,381,354,353,377,342,344,349,363,329,352,350,348,356,345]}",
      "inUptime": true,
      "lastBoxStats": null,
      "lastCheckStatus": "success",
      "lastError": "http error: Read timed out",
      "lastErrorDate": "2015-05-18T09:25:15Z",
      "lastMessage": "http 200",
      "lastMetric": "200",
      "lastRunDate": "2015-06-03T14:00:16Z",
      "lastStats": null,
      "lastSuccessDate": "2015-06-03T14:00:16Z",
      "lastTimer": 345,
      "lastUpdated": "2015-06-03T14:00:16Z",
      "lastWarningDate": null,
      "name": "Purity Plus",
      "nextRunDate": "2015-06-03T14:00:16Z",
      "severity": "critical",
      "startDate": null
    }
  ]
}

This endpoint retrieves all checks and their JSON encoded configuration attributes based on check type. Check data is encrypted in the database.

HTTP Request

GET $serverUrl/api/monitoring/checks

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort health Sort order
name Filter by name
phrase Filter by wildcard search of name and description
status Filter by health status: error, healthy, warning, muted
lastUpdated Date filter, restricts query to only load checks updated timestamp is more recent or equal to the date specified
deleted false Pass true to see checks that have been deleted.

Get a Specific Check

curl "$serverUrl/api/monitoring/checks/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "check:" {
    "id": 798,
    "account": {
      "id": 1
    },
    "active": true,
    "apiKey": "03850a42-b97a-4426-8733-924b8cf6e262",
    "availability": 99.9804109,
    "checkAgent": null,
    "checkIntegrations": [

    ],
    "checkInterval": 300,
    "checkSpec": null,
    "checkType": {
      "id": 1
    },
    "config": {"webMethod": "GET", "webUrl": "http://google.com"},
    "createIncident": true,
    "dateCreated": "2015-05-16T12:05:23Z",
    "deleted": false,
    "description": null,
    "health": 10,
    "history": "{\"checkDates\":[1433339580607,1433339595119,1433339613169,1433339625412,1433339641010,1433339655209,1433339670178,1433339687802,1433339700471,1433339715171,1433339730710,1433339745351,1433339764299,1433339775508,1433339790377,1433339805373,1433339820944,1433339835996,1433339850317,1433339865833,1433339880884,1433339895489,1433339910554,1433339925660,1433339940875,1433339956143,1433339970551,1433339985179,1433340000961,1433340015765],\"successList\":[true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true,true],\"healthList\":[10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10],\"timerList\":[347,410,338,337,365,361,373,374,358,337,350,505,342,338,358,359,381,354,353,377,342,344,349,363,329,352,350,348,356,345]}",
    "inUptime": true,
    "lastBoxStats": null,
    "lastCheckStatus": "success",
    "lastError": "http error: Read timed out",
    "lastErrorDate": "2015-05-18T09:25:15Z",
    "lastMessage": "http 200",
    "lastMetric": "200",
    "lastRunDate": "2015-06-03T14:00:16Z",
    "lastStats": null,
    "lastSuccessDate": "2015-06-03T14:00:16Z",
    "lastTimer": 345,
    "lastUpdated": "2015-06-03T14:00:16Z",
    "lastWarningDate": null,
    "name": "Purity Plus",
    "nextRunDate": "2015-06-03T14:00:16Z",
    "severity": "critical",
  }
}

This endpoint retrieves a specific check.

HTTP Request

GET $serverUrl/api/monitoring/checks/:id

URL Parameters

Parameter Description
ID ID of the check to retrieve

Create a Check

curl -XPOST "$serverUrl/api/monitoring/checks" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"check":{
    "name": "My Check",
    "checkType": {"code": "webGetCheck"},
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "checkInterval": 300,
    "checkAgent": null,
    "active": true,
    "config": {
      "webMethod": "GET",
      "webUrl": "http://google.com"
    }
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

POST $serverUrl/api/monitoring/checks

JSON Check Parameters

Parameter Default Description
name Unique name scoped to your account for the check
description Optional description field
checkType Check type you want to create, use code and a valid check type: {"code": "webGetCheck"}
checkInterval 300 Number of seconds you want between check executions (minimum value is 60, depending on your subscription plan)
inUptime true Used to determine if check should affect account wide availability calculations
active true Used to determine if check should be scheduled to execute
severity critical Severity level of incidents that are created when this check fails. They can be info, warning, or critical
checkAgent Specifies agent you want to run the check with i.e. {"id": 1} See Agents for more information
config JSON encoded list of parameters that varies by check type. See below for more information

Updating a Check

curl -XPUT "$serverUrl/api/monitoring/checks/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"check":{
    "name": "My Check",
    "checkType": {"code": "webGetCheck"},
    "inUptime": true,
    "severity": "critical",
    "description": null,
    "checkInterval": 300,
    "checkAgent": null,
    "active": true,
    "config": {
      "webMethod": "GET",
      "webUrl": "http://google.com"
    }
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

PUT $serverUrl/api/monitoring/checks/:id

JSON Check Parameters

Parameter Default Description
name Unique name scoped to your account for the check
description Optional description field
checkType Check type you want to create, use code and a valid check type: {"code": "webGetCheck"}
checkInterval 300 Number of seconds you want between check executions (minimum value is 60, depending on your subscription plan)
inUptime true Used to determine if check should affect account wide availability calculations
active true Used to determine if check should be scheduled to execute
severity critical Severity level of incidents that are created when this check fails. They can be info, warning, or critical
checkAgent Specifies agent you want to run the check with i.e. {"id": 1} See Agents for more information
config JSON encoded list of parameters that varies by check type. See below for more information

Check Types and Options

Morpheus supports a wide variety of check types. Each check type varies in its configuration payload when determining how the check should be run.

Creates a Web type Check

Web Get Check

{
  "check": {
    "name": "My Web Check",
    "checkType": {"code": "webGetCheck"},
    "config": {"webMethod":"GET","webUrl": "http://google.com", "checkUser":"basicUser","checkPassword":"basicPassword", "webTextMatch": "Login", "textCheckOn": "on"}
  }
}

Code: webGetCheck

Web check type allows you to perform a standard web request and validate the response came back successfully. Additionally, you can check for matching text within the result. There are several config parameters available for use with this type of check

Parameter Requirement Description
webMethod Yes HTTP method to use for testing (GET or POST)
webUrl Yes Web URL you wish to use to run a check on
checkUser No If you want to use HTTP Basic Authentication, populate this field with the username
checkPassword No If you want to use HTTP basic Authentication, populate this field with the password
textCheckOn No Set value to “on” if you want to turn on text matching
webTextMatch No Set the string you want to look for in the page source

MySQL Check

{
  "check": {
    "name": "MySql Check",
    "checkType": {"code": "mysqlCheck"},
    "config": {"dbHost":"db.example.org","dbPort": "3306", "dbUser":"basicUser","dbPassword":"basicPassword", "dbName": "mydb", "dbQuery": "select 1", "checkOperator": "lt", "checkResult": 2}
  }
}

Code: mysqlCheck

MySQL check allows you to execute a query so that you may validate the value returned in addition to verifying the database is responding. This can be useful for doing a slow query check or just making sure something isn’t growing out of control.

Parameter Requirement Description
dbHost Yes Hostname or IP address of the MySQL database
dbPort Yes MySQL Port (defaults to 3306)
dbUser Yes Database username
dbPassword Yes Database password, (all check data is encrypted inside the database)
dbName Yes Database name you would like to connect to
checkOperator No Can be set to lt (less than), gt (greater than), equal (Equal to) for comparison
checkResult No Numerical value to compare the check result against

SQL Server Check

{
  "check": {
    "name": "SQL Server Check",
    "checkType": {"code": "sqlCheck"},
    "config": {"dbHost":"db.example.org","dbPort": "3306", "dbUser":"basicUser","dbPassword":"basicPassword", "dbName": "mydb", "dbQuery": "select 1", "checkOperator": "lt", "checkResult": 2}
  }
}

Code: sqlCheck

SQL Server check allows to execute a query so that you may validate the value returned in addition to verifying the database is responding. This can be useful for doing a slow query check or just making sure something isn’t growing out of control.

Parameter Requirement Description
dbHost Yes Hostname or IP address of the SQL database
dbPort Yes SQL Port (defaults to 1433)
dbUser Yes Database username
dbPassword Yes Database password, (all check data is encrypted inside the database)
dbName Yes Database name you would like to connect to
checkOperator No Can be set to lt (less than), gt (greater than), equal (Equal to) for comparison
checkResult No Numerical value to compare the check result against

PostgreSQL Check

{
  "check": {
    "name": "PostgerSQL Check",
    "checkType": {"code": "postgresCheck"},
    "config": {"dbHost":"db.example.org","dbPort": "3306", "dbUser":"basicUser","dbPassword":"basicPassword", "dbName": "mydb", "dbQuery": "select 1", "checkOperator": "lt", "checkResult": 2}
  }
}

Code: postgresCheck

PostgreSQL check allows to execute a query so that you may validate the value returned in addition to verifying the database is responding. This can be useful for doing a slow query check or just making sure something isn’t growing out of control.

Parameter Requirement Description
dbHost Yes Hostname or IP address of the PostgreSQL database
dbPort Yes SQL Port (defaults to 5432)
dbUser Yes Database username
dbPassword Yes Database password, (all check data is encrypted inside the database)
dbName Yes Database name you would like to connect to
checkOperator No Can be set to lt (less than), gt (greater than), equal (Equal to) for comparison
checkResult No Numerical value to compare the check result against

Socket Check

{
  "check": {
    "name": "Socket Check",
    "checkType": {"code": "socketCheck"},
    "config": {"host":"test.example.org","port": "3306", "send":"blah","responseMatch":"OK"}
  }
}

Code: socketCheck

Socket check confirms a certain TCP port is up and responding in your environment. It can be configured do an initial send upon connect and compare and expected response of the service.

Parameter Requirement Description
host Yes Hostname or IP address of the socket server
port Yes TCP port
send No Connection string you might want to send to the service
responseMatch No Response from the service to match against

Elastic Search Check

{
  "check": {
    "name": "Socket Check",
    "checkType": {"code": "elasticSearchCheck"},
    "config": {"esHost":"test.example.org","esPort": "9200"}
  }
}

Code: elasticSearchCheck

Elasticsearch check is capable of connecting to your Elasticsearch, cluster or node, verifying its health. In addition, Morpheus will also pull statistical information such as: document size, capacity, and cpu usage.

Parameter Requirement Description
esHost Yes Hostname or IP address of the Elasticsearch server
esPort Yes Port to connect to the HTTP service

Push Check

{
  "check": {
    "name": "Push Check",
    "checkType": {"code": "pushCheck"}
  }
}

Code: pushCheck

A Push check is a check that is updated by a web hook. An external source is responsible for periodically submitting a check status. Please see the section on Push Checks API for details.

SSH Tunneling

SSH tunneling options allow the different check types to tunnel to a host via a proxy, and execute checks relative to the proxy. A SSH tunnel can use your account generated public and private key-pairs or SSH password. It is strongly recommended to use a key-pair.

To enable SSH tunneling for a check, add the following parameters to any check type config as seen earlier in the Check Types section.

{
  "check": {
    "name": "Socket Check",
    "checkType": {"code": "elasticSearchCheck"},
    "config": {"esHost":"test.example.org","esPort": "9200", "tunnelOn": "on", "sshHost": "example.org", "sshPort": 22, "sshUser": "happyapps"}
  }
}
Parameter Requirement Description
tunnelOn Yes Set to on to turn on tunneling
sshHost Yes Hostname or IP address of the proxy host
sshPort No Port for SSH on the proxy host, defaults to 22
sshUser Yes SSH user on the proxy host to login as
sshPassword No Password for user, if not using key based authentication

Mute a Check

curl -XPUT "$serverUrl/api/monitoring/checks/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": true
}

This endpoint can be used to toggle the mute state of a check.
This sets createIncident the opposite of muted.

Unmute a Check

curl -XPUT "$serverUrl/api/monitoring/checks/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false
}

The same endpoint is used to unmute by passing the parameter "muted":false.

HTTP Request

PUT $serverUrl/api/monitoring/checks/:id/mute

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

Mute All Checks

curl -XPUT "$serverUrl/api/monitoring/checks/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": true,
  "updated": 20
}

HTTP Request

PUT $serverUrl/api/monitoring/checks/mute-all

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

This endpoint can be used to toggle the mute state of all checks. This sets createIncident to the opposite of muted.

Unmute All Checks

curl -XPUT "$serverUrl/api/monitoring/checks/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false,
  "updated": 20
}

The same endpoint is used to unmute by passing the parameter "muted":false.

Delete a Check

curl -XDELETE "$serverUrl/api/monitoring/checks/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

A deleted check can be fetched from the API using the GET method to synchronize client side views, but can not be executed or updated.

HTTP Request

DELETE $serverUrl/api/monitoring/checks/:id

Check Types

A set of APIs for fetching a list of available check types is also provided. This API can make it useful for associating a check type code to an ID for check GET and POST requests. <!–

Get All Check Types

–> shell curl "$serverUrlmand/api/monitoring/check-types" -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "checkTypes": [
    {
      "id": 1,
      "code": "webGetCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "response",
      "name": "Web Check",
      "tunnelSupported": true
    },
    {
      "id": 2,
      "code": "mysqlCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "MySQL Check",
      "tunnelSupported": true
    },
    {
      "id": 3,
      "code": "mongoCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Mongo Check",
      "tunnelSupported": true
    },
    {
      "id": 4,
      "code": "elasticSearchCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "cluster status",
      "name": "Elastic Search Check",
      "tunnelSupported": true
    },
    {
      "id": 5,
      "code": "riakCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "write time",
      "name": "Riak Check",
      "tunnelSupported": true
    },
    {
      "id": 6,
      "code": "redisCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "key count",
      "name": "Redis Check",
      "tunnelSupported": true
    },
    {
      "id": 7,
      "code": "rabbitCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "queue count",
      "name": "Rabbit MQ Check",
      "tunnelSupported": true
    },
    {
      "id": 9,
      "code": "postgresCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Postgres Check",
      "tunnelSupported": true
    },
    {
      "id": 10,
      "code": "sqlCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Microsoft SQL Server",
      "tunnelSupported": true
    },
    {
      "id": 11,
      "code": "socketCheck",
      "createIncident": true,
      "defaultInterval": 60000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "response",
      "name": "Socket Check",
      "tunnelSupported": true
    },
    {
      "id": 12,
      "code": "pushCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Push API Check",
      "tunnelSupported": false
    },
    {
      "id": 13,
      "code": "pingCheck",
      "createIncident": true,
      "defaultInterval": 300000,
      "iconPath": null,
      "iconType": "upload",
      "inUptime": true,
      "metricName": "result",
      "name": "Ping Check",
      "tunnelSupported": true
    }
  ]
}

HTTP Request

GET $serverUrl/api/monitoring/check-types

Get Specific Check Type

curl "$serverUrl/api/monitoring/check-types/10" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this

{
  "success": true,
  "checkType": {
    "id": 10,
    "code": "sqlCheck",
    "createIncident": true,
    "defaultInterval": 300000,
    "iconPath": null,
    "iconType": "upload",
    "inUptime": true,
    "metricName": "result",
    "name": "Microsoft SQL Server",
    "tunnelSupported": true
  }
}

HTTP Request

GET $serverUrl/api/monitoring/check-types/1

Check Groups

These entities define Check Groups, a collection of checks.

curl "$serverUrl/api/monitoring/groups"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "checkGroup": {
    "id": 191,
    "account": {
      "id": 1
    },
    "instance": {
      "id": 273,
      "name": "testapache100"
    },
    "name": "testapache100",
    "description": null,
    "inUptime": true,
    "lastCheckStatus": null,
    "lastWarningDate": null,
    "lastErrorDate": null,
    "lastSuccessDate": null,
    "lastRunDate": "2018-02-08T06:41:00+0000",
    "lastError": null,
    "outageTime": 0,
    "lastTimer": 6,
    "health": 0,
    "history": null,
    "minHappy": 1,
    "lastMetric": null,
    "severity": "critical",
    "createIncident": true,
    "muted": false,
    "createdBy": {
      "id": 1,
      "username": "james"
    },
    "dateCreated": "2018-02-01T07:24:21+0000",
    "lastUpdated": "2018-02-11T07:38:28+0000",
    "availability": 99.77698404,
    "checkType": {
      "id": 1,
      "code": "webGetCheck",
      "name": "Web Check",
      "metricName": "response"
    }
  },
  "checks": [
    {
      "id": 195,
      "account": {
        "id": 1
      },
      "active": true,
      "availability": 99.77698403,
      "checkAgent": null,
      "checkInterval": 300000,
      "checkSpec": null,
      "checkType": {
        "id": 1,
        "code": "webGetCheck",
        "name": "Web Check",
        "metricName": "response"
      },
      "config": {
        "webUrl": "http://localhost:80"
      },
      "container": {
        "id": 271
      },
      "createIncident": true,
      "muted": false,
      "createdBy": {
        "id": 1,
        "username": "james"
      },
      "dateCreated": "2018-02-01T07:24:21+0000",
      "description": null,
      "endDate": null,
      "health": 0,
      "inUptime": true,
      "lastBoxStats": null,
      "lastCheckStatus": "error",
      "lastError": "unheard from beyond check interval limit.",
      "lastErrorDate": "2018-02-08T06:41:00+0000",
      "lastMessage": null,
      "lastMetric": null,
      "lastRunDate": "2018-02-08T06:41:00+0000",
      "lastStats": null,
      "lastSuccessDate": "2018-02-08T06:33:52+0000",
      "lastTimer": 6,
      "lastUpdated": "2018-02-11T07:38:28+0000",
      "lastWarningDate": null,
      "name": "testapache100",
      "nextRunDate": "2018-02-08T06:46:00+0000",
      "outageTime": 0,
      "severity": "critical",
      "startDate": null
    }
  ]
}

This endpoint retrieves all check groups.

HTTP Request

GET $serverUrl/api/monitoring/groups

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort health Sort order
name Filter by name
phrase Filter by wildcard search of name and description
status Filter by health status: error, healthy, warning, muted
lastUpdated Date filter, restricts query to only load checks updated timestamp is more recent or equal to the date specified
deleted false Pass true to see checks that have been deleted.

Get a Specific Check Group

curl "$serverUrl/api/monitoring/groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "checkGroup": {
    "id": 191,
    "account": {
      "id": 1
    },
    "instance": {
      "id": 273,
      "name": "testapache100"
    },
    "name": "testapache100",
    "description": null,
    "inUptime": true,
    "lastCheckStatus": null,
    "lastWarningDate": null,
    "lastErrorDate": null,
    "lastSuccessDate": null,
    "lastRunDate": "2018-02-08T06:41:00+0000",
    "lastError": null,
    "outageTime": 0,
    "lastTimer": 6,
    "health": 0,
    "history": null,
    "minHappy": 1,
    "lastMetric": null,
    "severity": "critical",
    "createIncident": true,
    "muted": false,
    "createdBy": {
      "id": 1,
      "username": "james"
    },
    "dateCreated": "2018-02-01T07:24:21+0000",
    "lastUpdated": "2018-02-11T07:38:28+0000",
    "availability": 99.77698404,
    "checkType": {
      "id": 1,
      "code": "webGetCheck",
      "name": "Web Check",
      "metricName": "response"
    }
  },
  "checks": [
    {
      "id": 195,
      "account": {
        "id": 1
      },
      "active": true,
      "availability": 99.77698403,
      "checkAgent": null,
      "checkInterval": 300000,
      "checkSpec": null,
      "checkType": {
        "id": 1,
        "code": "webGetCheck",
        "name": "Web Check",
        "metricName": "response"
      },
      "config": {
        "webUrl": "http://localhost:80"
      },
      "container": {
        "id": 271
      },
      "createIncident": true,
      "muted": false,
      "createdBy": {
        "id": 1,
        "username": "james"
      },
      "dateCreated": "2018-02-01T07:24:21+0000",
      "description": null,
      "endDate": null,
      "health": 0,
      "inUptime": true,
      "lastBoxStats": null,
      "lastCheckStatus": "error",
      "lastError": "unheard from beyond check interval limit.",
      "lastErrorDate": "2018-02-08T06:41:00+0000",
      "lastMessage": null,
      "lastMetric": null,
      "lastRunDate": "2018-02-08T06:41:00+0000",
      "lastStats": null,
      "lastSuccessDate": "2018-02-08T06:33:52+0000",
      "lastTimer": 6,
      "lastUpdated": "2018-02-11T07:38:28+0000",
      "lastWarningDate": null,
      "name": "testapache100",
      "nextRunDate": "2018-02-08T06:46:00+0000",
      "outageTime": 0,
      "severity": "critical",
      "startDate": null
    }
  ]
}

This endpoint retrieves a specific check.

HTTP Request

GET $serverUrl/api/monitoring/groups/:id

URL Parameters

Parameter Description
ID ID of the check to retrieve

Create a Check Group

curl -XPOST "$serverUrl/api/monitoring/groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"checkGroup":{
    "name": "My Check Group",
    "description": "A collection of checks",
    "checks": [5,6,7]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

POST $serverUrl/api/monitoring/groups

JSON Check Group Parameters

Parameter Default Description
name Unique name scoped to your account for the check group
description Optional description field
minHappy 1 Min Happy. This specifies the minimum number of checks within the group that must be happy to keep the group from becoming unhealthy.
inUptime true Used to determine if check should affect account wide availability calculations
severity critical Determines the maximum severity level this group can incur on an incident when failing. Default is critical. They can be info, warning, or critical
active true Used to determine if check group is active
checks [] Array of Check IDs

Updating a Check Group

curl -XPUT "$serverUrl/api/monitoring/groups/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"checkGroup":{
    checks: [5,6,7,8,9]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single check

HTTP Request

PUT $serverUrl/api/monitoring/groups/:id

JSON Check Group Parameters

Parameter Default Description
name Unique name scoped to your account for the check group
description Optional description field
inUptime true Used to determine if check should affect account wide availability calculations
active true Used to determine if check should be scheduled to execute
severity critical Severity level of incidents that are created when this check fails. They can be info, warning, or critical
checks Array of Check IDs

Mute a Check Group

curl -XPUT "$serverUrl/api/monitoring/groups/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint can be used to toggle the mute state of a check group on and off. This sets createIncident to the opposite of muted.

HTTP Request

PUT $serverUrl/api/monitoring/groups/:id/mute

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

Unmute a Check Group

curl -XPUT "$serverUrl/api/monitoring/groups/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false
}

The same endpoint is used to unmute by passing the parameter "muted":false.

Mute All Check Groups

curl -XPUT "$serverUrl/api/monitoring/groups/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": true,
  "updated": 5
}

HTTP Request

PUT $serverUrl/api/monitoring/groups/mute-all

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

Unmute All Check Groups

curl -XPUT "$serverUrl/api/monitoring/groups/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false,
  "updated": 5
}

The same endpoint is used to unmute by passing the parameter "muted":false.

Delete a Check Group

curl -XDELETE "$serverUrl/api/monitoring/groups/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

A deleted check group can be fetched from the API using the GET method to synchronize client side views, but can not be executed or updated.

HTTP Request

DELETE $serverUrl/api/monitoring/groups/:id

Incidents

These entities are incidents that result from Checks. The API provides a means to list all of an account’s incidents and also update, mute, close, and reopen them.

Get All Incidents

curl "$serverUrl/api/monitoring/incidents"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "incidents": [
    {
      "id": 12,
      "account": {
        "id": 1
      },
      "app": null,
      "autoClose": true,
      "channelId": "cdff5f78-19df-41e0-b6dc-2ab87cedeae5",
      "checkGroups": [

      ],
      "checks": [

      ],
      "comment": "",
      "displayName": "test-mysql",
      "duration": null,
      "endDate": null,
      "inUptime": true,
      "muted": false,
      "lastCheckTime": "2017-02-22T00:04:56+0000",
      "lastError": "unheard from beyond check interval limit.",
      "lastMessage": null,
      "name": "test-mysql",
      "resolution": "A network outage was resolved.",
      "severity": "critical",
      "severityId": 20,
      "startDate": "2017-02-22T00:04:56+0000",
      "status": "open",
      "visibility": "private"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 25,
    "total": 63
  }
}

This endpoint retrieves all incidents.

HTTP Request

GET $serverUrl/api/monitoring/incidents

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
status Filter by status
severity Filter by severity

Get a Specific Incident

curl "$serverUrl/api/monitoring/incidents/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "incident": {
    "id": 1,
    "account": {
      "id": 1
    },
    "app": null,
    "autoClose": true,
    "channelId": "3f2fb251-9f87-4e28-88f7-7e0df24f4d50",
    "checkGroups": [
      {
        "id": 129,
        "name": "test-nginx"
      }
    ],
    "checks": [

    ],
    "comment": null,
    "displayName": "test-nginx",
    "duration": null,
    "endDate": "2018-03-26T11:00:34+0000",
    "inUptime": true,
    "muted": false,
    "lastCheckTime": "2018-03-23T23:06:03+0000",
    "lastError": "unheard from beyond check interval limit.",
    "lastMessage": null,
    "name": "test-nginx",
    "resolution": null,
    "severity": "critical",
    "severityId": 20,
    "startDate": "2018-03-23T23:06:03+0000",
    "status": "closed",
    "visibility": "private"
  },
  "issues": [
    {
      "id": 178,
      "attachmentType": "Group",
      "app": null,
      "available": false,
      "check": null,
      "checkGroup": {
        "id": 129,
        "name": "test-nginx"
      },
      "checkStatus": null,
      "endDate": "2018-03-26T11:00:33+0000",
      "health": 0,
      "inUptime": true,
      "muted": false,
      "incident": {
        "id": 41
      },
      "lastCheckTime": null,
      "lastError": null,
      "lastMessage": null,
      "name": "test-nginx",
      "severity": "critical",
      "severityId": 10,
      "startDate": "2018-03-23T23:06:03+0000",
      "status": "closed"
    }
  ]
}

This endpoint retrieves a specific incident.

HTTP Request

GET $serverUrl/api/monitoring/incidents/:id

URL Parameters

Parameter Description
ID ID of the incident to retrieve

Updating an Incident

curl -XPUT "$serverUrl/api/monitoring/incidents/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"incident":{
    "resolution": "We fixed the problem",
  }}'

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint can be used to update certain properties of an incident.

HTTP Request

PUT $serverUrl/api/monitoring/incidents/:id

JSON Parameters

Parameter Default Description
resolution Description of the resolution to this incident
comment Comment on this incident
status Set status (open or closed)
severity Set severity (critical, warning or info)
name Set display name(subject)
startDate Set start time
endDate Set end time

Mute an Incident

curl -XPUT "$serverUrl/api/monitoring/incidents/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": true
}

This endpoint can be used to toggle the mute state of an incident. This sets inUptime to the opposite of muted.

HTTP Request

PUT $serverUrl/api/monitoring/incidents/:id/mute

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

Unmute an Incident

curl -XPUT "$serverUrl/api/monitoring/incidents/1/mute" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false
}

The same endpoint is used to unmute by passing the parameter "muted":false.

Mute All Incidents

curl -XPUT "$serverUrl/api/monitoring/incidents/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":true}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": true,
  "updated": 11
}

This endpoint can be used to toggle the mute state of all open incidents. This sets inUptime to the opposite of muted.

HTTP Request

PUT $serverUrl/api/monitoring/incidents/mute-all

JSON Parameters

Parameter Default Description
muted true Set to false to unmute

Unmute all Incidents

curl -XPUT "$serverUrl/api/monitoring/incidents/mute-all" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"muted":false}'

The above command returns JSON structure like this:

{
  "success": true,
  "muted": false,
  "updated": 11
}

The same endpoint is used to unmute by passing the parameter "muted":false.

Close an Incident

curl -XDELETE "$serverUrl/api/monitoring/incidents/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true,
  "msg": "Incident 1 is closed"
}

HTTP Request

DELETE $serverUrl/api/monitoring/incidents/:id

Reopen an Incident

curl -XPUT "$serverUrl/api/monitoring/incidents/1/reopen" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON structure like this:

{
  "success": true,
  "msg": "Incident 1 is now open again"
}

This endpoint can be used to toggle the status of an incident back to open.

HTTP Request

PUT $serverUrl/api/monitoring/incidents/:id/reopen

Create an Incident

curl -XPOST "$serverUrl/api/monitoring/incidents" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"incident":{
        "comment": "This is a summary of the incident",
        "resolution": null,
        "status": "open",
        "severity": "warning",
        "name": "Incident Name",
        "startDate": "2019-10-20T19:42:00Z",
        "endDate": "2019-10-21T19:42:00Z",
        "inUptime": true
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single incident

This endpoint can be used to create an incident.

HTTP Request

POST $serverUrl/api/monitoring/incidents

JSON Parameters

Parameter Default Description
resolution Description of the resolution to this incident
comment Comment on this incident, updates summary field
status Set status (open or closed)
severity Set severity (critical, warning or info)
name Set display name(subject)
startDate Set start time
endDate Set end time
inUptime Set ‘In Availability’

Contacts

These entities are notification settings such as name, email and phone number. Contacts are used by alerts to send notifications.

Get All Contacts

curl "$serverUrl/api/monitoring/contacts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "contacts": [
    {
      "id": 1,
      "emailAddress": "admin@yourapp.com",
      "name": "Admin",
      "smsAddress": "555-555-5555",
      "slackHook": null
    }
  ],
  "meta": {
    "offset": 0,
    "max": "1",
    "size": 1,
    "total": 8
  }
}

This endpoint retrieves all contacts.

HTTP Request

GET $serverUrl/api/monitoring/contacts

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
name If specified will return an exact match on name
phrase If specified will return a partial match on name or email or sms

Get a Specific Contact

curl "$serverUrl/api/monitoring/contacts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "contact": {
    "id": 1,
    "emailAddress": "admin@yourapp.com",
    "name": "Admin",
    "smsAddress": "555-555-5555",
    "slackHook": null
  }
}

This endpoint retrieves a specific contact.

HTTP Request

GET $serverUrl/api/monitoring/contacts/:id

URL Parameters

Parameter Description
ID ID of the contact

Create a Contact

curl -XPOST "$serverUrl/api/monitoring/contacts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"contact":{
    "name": "IT Admin",
    "emailAddress": "admin@yourapp.com",
    "smsAddress": "555-555-6789"
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single contact

HTTP Request

POST $serverUrl/api/monitoring/contacts

JSON Parameters

Parameter Default Description
name Unique name scoped to your account for the contact
emailAddress Email notification address
smsAddress SMS notification address
slackHook Slack Hook

Updating a Contact

curl -XPUT "$serverUrl/api/monitoring/contacts/3" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"contact":{
    "name": "Jane Doe"
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single contact

HTTP Request

PUT $serverUrl/api/monitoring/contacts/:id

URL Parameters

Parameter Description
ID ID of the contact

JSON Parameters

Parameter Default Description
name Unique name scoped to your account for the contact
emailAddress Email notification address
smsAddress SMS notification address
slackHook Slack Hook

Delete a Contact

curl -XDELETE "$serverUrl/api/monitoring/contacts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/monitoring/contacts/:id

URL Parameters

Parameter Description
ID ID of the contact

Alerts

Alerts are rules that define who is notified about monitoring incidents. An alert can be configured for specific Checks, Check Groups, and/or Monitor Apps. Alert notification recipients are defined as Contacts.

Get All Alerts

curl "$serverUrl/api/monitoring/alerts"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "alerts": [
    {
      "id": 1,
      "name": "My Alert",
      "allApps": true,
      "allChecks": false,
      "allGroups": false,
      "active": true,
      "minSeverity": "critical",
      "minDuration": 0,
      "dateCreated": "2019-10-23T01:08:22+0000",
      "lastUpdated": "2019-10-23T01:08:22+0000",
      "checks": [
        1,2,3
      ],
      "checkGroups": [

      ],
      "apps": [

      ],
       "contacts": [
        {
          "id": 1,
          "name": "admin",
          "method": "emailAddress,smsAddress",
          "notify": false,
          "close": true
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves a paginated list of alerts.

HTTP Request

GET $serverUrl/api/monitoring/alerts

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
lastUpdated Date filter, restricts query to only load alerts updated timestamp is more recent or equal to the date specified

Get a Specific Alert

curl "$serverUrl/api/monitoring/alerts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "alert": {
    "id": 1,
    "name": "My Alert",
    "allApps": true,
    "allChecks": false,
    "allGroups": false,
    "active": true,
    "minSeverity": "critical",
    "minDuration": 0,
    "dateCreated": "2019-10-22T19:48:38+0000",
    "lastUpdated": "2019-10-22T19:48:38+0000",
    "checks": [

    ],
    "checkGroups": [

    ],
    "apps": [

    ],
    "contacts": [
      {
        "id": 1,
        "name": "admin",
        "method": "emailAddress",
        "notify": true,
        "close": true
      }
    ]
  }
}

This endpoint retrieves a specific alert.

HTTP Request

GET $serverUrl/api/monitoring/alerts/:id

URL Parameters

Parameter Description
:id ID of the alert

Create an Alert

curl -XPOST "$serverUrl/api/monitoring/alerts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '"alert": {
    "name": "My Alert",
    "minSeverity": "critical",
    "minDuration": 0,
    "allChecks": false,
    "checks": [
      1,2,3
    ],
    "allGroups": false,
    "checkGroups": [

    ],
    "allApps": false,
    "apps": [

    ],
    "contacts": [
      {
        "id": 1,
        "method": "emailAddress,smsAddress",
        "notify": true,
        "close": true
      }
    ]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single alert

HTTP Request

POST $serverUrl/api/monitoring/alerts

JSON Alert Parameters

Parameter Default Description
name Unique name scoped to your account for the alert
minDuration 0 Duration in minutes of the delay before sending notification(s). Default is immediate (0).
minSeverity critical Severity level threshold for sending notifications. They can be info, warning, or critical
active true Set to false to disable notifications.
allChecks false Trigger for all checks.
allGroups false Trigger for all check groups.
allApps false Trigger for all monitor apps.
checks Array of Check IDs. Trigger for specific checks.
groups Array of Check Group IDs. Trigger for specific check groups.
apps Array of Monitor App IDs. Trigger for specific monitor apps.
contacts Array of objects. See Alert Contact Parameters.

Alert Contacts Parameters

Parameter Default Description
id Contact ID. The contact to be notified.
method none Method(s) to notify by. Email is emailAddress, SMS is smsAddress and both Email and SMS is emailAddress,smsAddress.
notify false Notify On Change. Send notifications when an incident is created or updated.
close false Notify On Close. Send notifications when an incident is closed.

This defines a contact to notify and how to notify them. Be sure to pass "method":"emailAddress" and "notify":true, otherwise notifications will not be sent to the contact.

Updating an Alert

curl -XPUT "$serverUrl/api/monitoring/alerts/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '"alert": {
    "minSeverity": "critical",
    "minDuration": 0,
    "allChecks": false,
    "checks": [1,2,3,4,5],
    "contacts": [
      {
        "id": 1,
        "method": "emailAddress",
        "notify": true,
        "close": true
      }
    ]
  }}'

The above command returns a similar JSON structure when submitting a GET request for a single alert

HTTP Request

PUT $serverUrl/api/monitoring/alerts/:id

URL Parameters

Parameter Description
:id ID of the alert

JSON Alert Parameters

Parameter Default Description
name Unique name scoped to your account for the alert
minDuration 0 Duration in minutes of the delay before sending notification(s). Default is immediate (0).
minSeverity critical Severity level threshold for sending notifications. They can be info, warning, or critical
active true Set to false to disable notifications.
allChecks false Trigger for all checks.
allGroups false Trigger for all check groups.
allApps false Trigger for all monitor apps.
checks Array of Check IDs. Trigger for specific checks.
groups Array of Check Group IDs. Trigger for specific check groups.
apps Array of Monitor App IDs. Trigger for specific monitor apps.
contacts Array of objects. See Alert Contact Parameters.

Delete an Alert

curl -XDELETE "$serverUrl/api/monitoring/alerts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/monitoring/alerts/:id

URL Parameters

Parameter Description
:id ID of the alert

Tools

The Tools API endpoints provide access to Cypher, Archives, Image Builder and Self Service.

Cypher

Cypher at its core is a secure Key/Value store. But what makes cypher useful is the ability to securely store or generate credentials to connect to your instances. Not only are these credentials encrypted but by using a cypher you don’t have to burn in connection credentials between instances into your apps.

Cypher keys can be revoked, either through lease timeouts or manually. So even if somebody were to gain access to your keys you could revoke access to the keys and generate new ones for your applications.

Cypher Authentication

The Cypher API endpoints allow authentication via a special header or the standard [Authorization] header. Instead of an access token, an execution lease token can be used to authenticate. An execution lease will be issued by Morpheus for certain tasks, such as Ansible, which can then use the token to read cypher keys.

Cypher has the following headers and url parameters available for authentication:

Name Type Description
X-Cypher-Token HTTP Header An access token or an execution lease token.
X-Vault-Token HTTP Header An access token or an execution lease token.
X-Morpheus-Lease HTTP Header An execution lease token.
leaseToken URL Parameter An execution lease token.

List Cypher Keys

curl -XLIST "$serverUrl/api/cypher?list=true" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "data": {
    "keys": [
      "password/15/mypassword",
      "secret/foo"
    ]
  },
  "cyphers": [
    {
      "itemKey": "password/15/mypassword",
      "leaseTimeout": 2764800000,
      "expireDate": "2019-03-23T10:17:52Z",
      "dateCreated": "2019-02-19T10:17:52Z",
      "lastUpdated": "2019-02-19T10:17:52Z",
      "lastAccessed": "2019-02-19T10:17:52Z"
    },
    {
      "itemKey": "secret/foo",
      "leaseTimeout": 2764800000,
      "expireDate": "2019-03-25T17:14:33Z",
      "dateCreated": "2019-02-21T17:14:33Z",
      "lastUpdated": "2019-02-21T17:14:33Z",
      "lastAccessed": "2019-02-21T17:14:33Z"
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all cypher keys associated with the account, or user.

This endpoint is available http method LIST. The GET method can be used to list keys as well, by passing the query parameter list=true.

HTTP Request

LIST $serverUrl/api/cypher/:key?list=true

URL Parameters

Parameter Description
key If specified will match the start of the key.

Query Parameters

Parameter Default Description
list Set to true for list behavior with HTTP GET.
phrase If specified will match any part of key
key If specified will return an exact match of key
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort key Sort order
direction asc Sort direction, use ‘desc’ to reverse sort

Read a Cypher Key

curl "$serverUrl/api/cypher/secret/foo" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "data": {
    "foo":"bar",
    "briefing":"top secret info"
  },
  "type": "object",
  "lease_duration": 2764800,
  "cypher": {
    "itemKey": "secret/foo",
    "leaseTimeout": 2764800000,
    "expireDate": "2019-03-18T20:15:51Z",
    "dateCreated": "2019-02-14T20:15:51Z",
    "lastUpdated": "2019-02-14T20:15:51Z",
    "lastAccessed": "2019-02-14T20:15:51Z"
  }
}

This endpoint retrieves a specific cypher key. The value of the key is decrypted and returned as data. It may be a String or an object with many {"key":"value"} pairs. The type depends on the cypher mount’s capabilities and what type of data was written to the key. For example the secret/ mount allows either a string or an object, while the password/ mount will always store and return a string.

HTTP Request

GET $serverUrl/api/cypher/:key

URL Parameters

Parameter Description
key The full cypher key including the mount prefix.

Query Parameters

Parameter Default Description
ttl 0 Time to Live. The lease duration in seconds, or a human readable format eg. 15m, 8h, 7d. The default is 0 meaning Never expires. This only is applied if the cypher does not yet exist and is created.
readonly false Do not automatically create a key. This only applies to mount types uuid, key, password.

Read a Cypher with Lease

curl "$serverUrl/api/cypher/password/15/mypassword" \
  -H "X-Lease-Token: 6f4d3563-22ef-404f-8b81-c13d093cd55a"

The above command returns JSON structured like reading a key with normal authentication:

{
  "data": "B[,t;ng[5[lg&th",
  "type": "string",
  "lease_duration": 432000000,
  "cypher": {
    "itemKey": "password/15/mypassword",
    "leaseTimeout": 432000000,
    "expireDate": "2019-02-26T21:35:20Z",
    "dateCreated": "2019-02-21T21:35:20Z",
    "lastUpdated": "2019-02-21T21:35:20Z",
    "lastAccessed": "2019-02-21T21:35:20Z"
  }
}

HTTP Request

GET $serverUrl/api/cypher/:key

URL Parameters

Parameter Default Description
key The cypher key including the mount prefix.

Query Parameters

Parameter Default Description
ttl 0 Time to Live. The lease duration in seconds, or a human readable format eg. 15m, 8h, 7d. The default is 0 meaning Never expires. This only is applied if the cypher does not yet exist and is created.

Write a Cypher

curl -XPOST "$serverUrl/api/cypher/secret/foo" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"foo":"bar", "zip":"zap"}'

The above command returns JSON structured like readding a cypher key:.

This endpoint will create or update a cypher key.

HTTP Request

POST $serverUrl/api/cypher/:key

This endpoint is available via both methods POST and PUT.

URL Parameters

Parameter Description
key The full cypher key including the mount prefix.

Query Parameters

Parameter Default Description
ttl 0 Time to Live. The lease duration in seconds, or a human readable format eg. '15m’, 8h, '7d’.
value The secret value to be stored. Only required for certain mounts. Some mounts generate their own value and do not require a value to be passed. eg. uuid, key and password.
type The type of data being stored, string or object. The data type depends on the cypher mount being used. Most mounts use string as their data type, but secret uses object by default. You can store a string instead by passing type=string. This means the data value returned by the API will be a string instead of an object.

JSON Parameters

The following parameters are available under the root context of the JSON body.

Parameter Default Description
ttl 0 Time to Live. The lease duration in seconds, or a human readable format eg. 15m, 8h, 7d. The default is 0 meaning Never expires. This only is applied if the cypher does not yet exist and is created.
value The secret value to be stored. This is only parsed if type is passed as string.

The secret mount is capable of storing the entire JSON object as key=value pairs, or just a single string. To store a string instead, use the value query parameter instead of JSON, or pass type=string.

There are a couple of special keys that the API will look for in the payload.

The ttl key is a special key that if present in the payload will be parsed and used as the ttl parameter (lease duration in seconds).

The value key is a special key that if present in the payload will be parsed and used as the secret data (instead of the entire payload). This is true when type=string.

Key

The key includes a mount prefix separated by a /. For example, the key secret/foo uses the secret mount.

Available mounts

Keys can have different behaviors depending on the specified mount engine.

Mount Description Example
password Generates a secure password of specified character length in the key pattern (or 15) with symbols, numbers, upper case, and lower case letters (i.e. password/15/mypass generates a 15 character password). password/15/mypass
tfvars This is a module to store a tfvars file for terraform. tfvars/mytfvar
secret This is the standard secret module that stores a key/value in encrypted form. Capable of storing entire JSON object or a String. secret/foo
uuid Returns a new UUID by key name when requested and stores the generated UUID by key name for a given lease timeout period. uuid/autoMac1
key Generates a Base 64 encoded AES Key of specified bit length in the key pattern (i.e. key/128/mykey generates a 128-bit key) key/128/mykey

Lease Time

Quick MS Time Reference:

Time MS
Day 86400000
Week 604800000
Month (30 days) 2592000000
Year 31536000000

Delete a Cypher

curl -XDELETE "$serverUrl/api/cypher/secret/foo" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a cypher from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/cypher/:key

URL Parameters

Parameter Description
key The full cypher key including the mount prefix.

Archives

Archives provides a way to store your files and make them available for download by your Scripts and Users.

Archives are organized by buckets. Each bucket has a unique name that is used to identify it in URLs and Scripts.

Get All Archive Buckets

curl "$serverUrl/api/archives/buckets" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "archiveBuckets": [

    {
      "id": 1,
      "name": "testbucket",
      "description": "a test archive with local storage",
      "storageProvider": {
        "id": 2,
        "name": "testdrive2"
      },
      "owner": {
        "id": 1,
        "name": "root"
      },
      "createdBy": null,
      "isPublic": true,
      "visibility": "private",
      "code": "454ed1af504f",
      "filePath": "morpheus-archives/454ed1af504f/",
      "rawSize": 65154,
      "fileCount": 16,
      "accounts": [

      ],
      "dateCreated": "2017-06-14T14:09:01Z",
      "lastUpdated": "2017-06-14T14:09:01Z"
    },
    {
      "id": 2,
      "name": "s3bucket",
      "description": "an test archive using s3",
      "storageProvider": {
        "id": 3,
        "name": "test-bucket"
      },
      "owner": {
        "id": 1,
        "name": "root"
      },
      "createdBy": null,
      "isPublic": false,
      "visibility": "private",
      "code": "4fdcad04901b",
      "filePath": "morpheus-archives/4fdcad04901b/",
      "rawSize": 70389,
      "fileCount": 18,
      "accounts": [

      ],
      "dateCreated": "2017-06-14T16:31:19Z",
      "lastUpdated": "2017-06-14T16:31:19Z"
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 50
  }
}

This endpoint retrieves all archive buckets associated with the account.

HTTP Request

GET $serverUrl/api/archives/buckets

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Archive Bucket

curl "$serverUrl/api/archives/buckets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "archiveBucket": {
    "id": 1,
    "name": "mybucket",
    "description": "a test bucket with local storage",
    "storageProvider": {
      "id": 10,
      "name": "testdrive3"
    },
    "owner": {
      "id": 1,
      "name": "root"
    },
    "createdBy": null,
    "isPublic": false,
    "visibility": "private",
    "code": "9dab5b3f4ada",
    "filePath": "morpheus-archives/9dab5b3f4ada/",
    "rawSize": 73909,
    "fileCount": 15,
    "accounts": [

    ],
    "dateCreated": "2018-07-20T04:07:09Z",
    "lastUpdated": "2018-07-26T19:38:17Z",
    "isOwner": true
  }
}

This endpoint retrieves a specific archive bucket.

HTTP Request

GET $serverUrl/api/archives/buckets/:id

URL Parameters

Parameter Description
ID The ID of the archive bucket to retrieve

Create an Archive Bucket

curl -XPOST "$serverUrl/api/archives/buckets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "archiveBucket": {
    "name": "mybucket",
    "description": "my archive bucket",
    "storageProvider": {
      "id": 2
    },
    "visibility": "private",
    "isPublic": false
  }
}'

The above command returns JSON structured like getting a single archive bucket:

HTTP Request

POST $serverUrl/api/archives/buckets

JSON Parameters

Parameter Default Description
name A name for the archive bucket. Must be globally unique.
description A description for the archive bucket
storageProvider Storage Provider
isPublic false Public URL - Set to true to allow anonymous access
visibility private Visibility - Set to public to allow all tenants
accounts Tenants - Grant read only access to certain tenants

Update an Archive Bucket

curl -XPUT "$serverUrl/api/archives/buckets/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "archiveBucket": {
    "description": "our secure file store",
    "isPublic": false
  }
}'

The above command returns JSON structured like getting a single archive bucket.

HTTP Request

PUT $serverUrl/api/archives/buckets/1

URL Parameters

Parameter Description
ID The ID of the archive bucket

JSON Parameters

Parameter Default Description
name A name for the archive bucket. Must be globally unique
description A description for the archive bucket
isPublic false Public URL - Set to true to allow anonymous access
visibility private Visibility - Set to public to allow all tenants access.
accounts Tenants - Grant read only access to certain tenants

Delete an Archive Bucket

curl -XDELETE "$serverUrl/api/archives/buckets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete an archive bucket from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/archives/buckets/:id

URL Parameters

Parameter Description
ID The ID of the archive bucket

Get All Archive Files

curl "$serverUrl/api/archives/buckets/mybucket/files/" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "parentDirectory": null,
  "archiveFiles": [
    {
      "id": 951,
      "name": "myapp",
      "filePath": "myapp",
      "archiveBucket": {
        "id": 38,
        "name": "mybucket",
        "isPublic": false
      },
      "createdBy": {
        "username": "admin"
      },
      "isDirectory": true,
      "status": "Active",
      "rawSize": 26719,
      "contentType": null,
      "dateCreated": "2018-07-26T19:38:17Z",
      "lastUpdated": "2018-07-26T19:38:17Z"
    },
    {
      "id": 933,
      "name": "readme.txt",
      "filePath": "readme.txt",
      "archiveBucket": {
        "id": 38,
        "name": "mybucket",
        "isPublic": false
      },
      "createdBy": {
        "username": "admin"
      },
      "isDirectory": false,
      "status": "Active",
      "rawSize": 47104,
      "contentType": "text/plain",
      "dateCreated": "2018-07-20T04:07:33Z",
      "lastUpdated": "2018-07-20T04:07:33Z"
    }
  ],
  "archiveBucket": {
    "id": 38,
    "name": "mybucket",
    "description": "a test bucket with local storage",
    "storageProvider": {
      "id": 10,
      "name": "testdrive3"
    },
    "owner": {
      "id": 1,
      "name": "root"
    },
    "createdBy": null,
    "isPublic": false,
    "visibility": "private",
    "code": "9dab5b3f4ada",
    "filePath": "morpheus-archives/9dab5b3f4ada/",
    "rawSize": 73823,
    "fileCount": 3,
    "accounts": [

    ],
    "dateCreated": "2018-07-20T04:07:09Z",
    "lastUpdated": "2018-07-26T19:38:17Z"
  },
  "isOwner": true,
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 50
  }
}

This endpoint retrieves all files in an archive bucket under the specified filePath.

HTTP Request

GET $serverUrl/api/archives/buckets/:bucket/files/:filePath

URL Parameters

Parameter Description
bucket The Name or ID of the archive bucket
filePath The directory to search under. The root directory / is the default.

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on filePath
fullTree false Include files under sub directories too. This is always true when searching with phrase.
curl "$serverUrl/api/archives/files/954" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "archiveFile": {
    "id": 954,
    "name": "articles_controller.rb",
    "filePath": "future/app/controllers/agents_controller.rb",
    "archiveBucket": {
      "id": 38,
      "name": "b10",
      "isPublic": false
    },
    "createdBy": {
      "username": "tom"
    },
    "isDirectory": false,
    "status": "Active",
    "rawSize": 8534,
    "contentType": "application/octet-stream",
    "downloadCount": 0,
    "dateCreated": "2017-07-26T19:38:17Z",
    "lastUpdated": "2017-07-27T02:03:49Z"
  },
  "isOwner": true
}

Get details about a specific archive file.

HTTP Request

GET $serverUrl/api/archives/files/:fileId

URL Parameters

Parameter Description
fileId The ID of the archive file

Upload Archive File

curl -XPOST "$serverUrl/api/archives/buckets/mybucket/files/myapp/config/?filename=application.rb" \
  -H "Authorization: BEARER $accessToken" \
  --data-binary '@/path/to/file'

The above command returns JSON structure like this:

{
  "success": true
}

Upload a file to the specified archive bucket and file path.

HTTP Request

POST $serverUrl/api/archives/buckets/:bucket/files/:filePath

URL Parameters

Parameter Description
bucket The Name or ID of the archive bucket
filePath The directory for the file being uploaded. The root directory / is the default.

Query Parameters

Parameter Description
filename Specify a filename for archive file. The base filename of the uploaded file is the default.

Download an Archive File

curl -XGET "$serverUrl/api/archives/download/mybucket/myapp/config/application.rb" \
  -H "Authorization: BEARER $accessToken"

The above command returns the contents of the specified file as an attachment with Content-Type dicated by the file

Download the file as an authorized user with access to the bucket.

HTTP Request

GET $serverUrl/api/archives/download/:bucket/:filePath

URL Parameters

Parameter Description
bucket The Name or ID of the archive bucket
filePath The full path of the file being downloaded

Download a Public Archive File

curl -XGET "$serverUrl/public-archives/download/mybucket/pubdemo/GREETINGS.md"

The above command returns the contents of the file as an attachment with Content-Type dicated by the file

Files in an archive bucket that has Public URL enabled can be downloaded via this endpoint without any authentication, anonymously.

HTTP Request

GET $serverUrl/public-archives/download/:bucket/:filePath

URL Parameters

Parameter Description
bucket The Name or ID of the archive bucket
filePath The full path of the file being downloaded

Delete Archive File

curl -XDELETE "$serverUrl/api/archives/files/99" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Permanently delete a file or directory.

HTTP Request

DELETE $serverUrl/api/archives/files/:fileId

URL Parameters

Parameter Description
fileId The ID of the archive file

HTTP Request

curl "$serverUrl/api/archives/files/1/links"
  -H "Authorization: BEARER $accessToken"
{
  "archiveFileLinks": [
    {
      "id": 2,
      "secretAccessKey": "6e37727235041746",
      "archiveFile": {
        "id": 1,
        "name": "config.ini",
        "filePath": "config.ini"
      },
      "createdBy": {
        "username": "admin"
      },
      "dateCreated": "2018-09-20T21:15:38Z",
      "lastUpdated": "2018-09-20T21:15:38Z",
      "lastAccessDate": null,
      "expirationDate": null,
      "downloadCount": 0
    },
    {
      "id": 1,
      "secretAccessKey": "6562129e9e546b9",
      "archiveFile": {
        "id": 1,
        "name": "config.ini",
        "filePath": "config.ini"
      },
      "createdBy": {
        "username": "admin"
      },
      "dateCreated": "2018-09-20T21:06:04Z",
      "lastUpdated": "2018-09-20T21:09:26Z",
      "lastAccessDate": null,
      "expirationDate": "2018-09-20T21:26:04Z",
      "downloadCount": 1
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 50
  }
}

This endpoint retrieves the links that have been created for the specified file.

HTTP Request

GET $serverUrl/api/archives/files/:fileId/links

URL Parameters

Parameter Description
fileId The ID of the archive file
curl -XPOST "$serverUrl/api/archives/files/:fileId/links" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \

The above command returns JSON structured like this:

{
  "success": true,
  "secretAccessKey": "45a214fce9a546b9"
}

This returns a secret token that can be used to download the file via a public url, without any other authentication or authorization. File links can be set to expire after a certain amount of time.

See Download an Archive File Link

HTTP Request

POST $serverUrl/api/archives/files/:fileId/links

URL Parameters

Parameter Description
fileId The ID of the archive file

Query Parameters

Parameter Default Description
expireSeconds 0 Time to live in seconds. 0 means do not expire.
curl -XDELETE "$serverUrl/api/archives/files/1/links/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \

The above command returns JSON structured like this:

{
  "success": true
}

This will delete the link from the system, so it can no longer be used.

HTTP Request

DELETE $serverUrl/api/archives/files/:fileId/links/:linkId

URL Parameters

Parameter Description
fileId The ID of the archive file
linkId The ID of the archive file link
curl -XGET "$serverUrl/public-archives/link?s=45a214fce9a546b9"

The above command returns the contents of the file as an attachment with Content-Type dicated by the file

Download an archive file lin

HTTP Request

GET $serverUrl/public-archives/link?s=:secretAccessToken

URL Parameters

Parameter Description
s The secret access token for the archive file being downloaded. See Create An Archive File Link

Image Builds

Image Builds are used to generate Virtual Images for your Morpheus Library.

Get All Image Builds

curl "$serverUrl/api/image-builds" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "imageBuilds": [
    {
      "id": 1,
      "account": {
        "id": 1,
        "name": "root"
      },
      "type": {
        "id": 1,
        "code": "vmware",
        "name": "VMware"
      },
      "site": {
        "id": 1,
        "name": "my-group"
      },
      "zone": {
        "id": 1,
        "name": "my-vmware"
      },
      "name": "testbuild",
      "description": "a test build",
      "bootScript": {
        "id": 2,
        "fileName": "debian standard"
      },
      "bootCommand": null,
      "preseedScript": {
        "id": 2,
        "fileName": "debian 8"
      },
      "scripts": [
        {
          "id": 114,
          "name": "blah.txt",
          "type": "bash",
          "phase": "postProvision"
        }
      ],
      "sshUsername": "builderbot",
      "sshPassword": "************",
      "storageProvider": null,
      "buildOutputName": "mytestbuild",
      "conversionFormats": null,
      "isCloudInit": false,
      "vmToolsInstalled": true,
      "keepResults": 2,
      "config": {
      },
      "lastResult": {
        "id": 70,
        "imageBuild": {
          "id": 21,
          "name": "testbuild"
        },
        "buildNumber": 6,
        "startDate": "2017-09-28T05:48:03Z",
        "endDate": null,
        "statusMessage": "Initializing",
        "statusPercent": 0.0,
        "statusEta": null,
        "status": "running",
        "errorMessage": null,
        "createdBy": {
          "username": "admin"
        },
        "tempInstance": null,
        "virtualImages": [

        ]
      },
      "executionCount": 2
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all image builds associated with the account.

HTTP Request

GET $serverUrl/api/image-builds

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Image Build

curl "$serverUrl/api/image-builds/4" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this (config omited) :

{
  "imageBuild": {
    "id": 1,
    "account": {
      "id": 1,
      "name": "root"
    },
    "type": {
      "id": 1,
      "code": "vmware",
      "name": "VMware"
    },
    "site": {
      "id": 1,
      "name": "my-group"
    },
    "zone": {
      "id": 1,
      "name": "my-vmware"
    },
    "name": "testbuild",
    "description": "a test build",
    "bootScript": {
      "id": 2,
      "fileName": "debian standard"
    },
    "bootCommand": null,
    "preseedScript": {
      "id": 2,
      "fileName": "debian 8"
    },
    "scripts": [
      {
        "id": 114,
        "name": "cleanup.sh",
        "type": "bash",
        "phase": "postProvision"
      }
    ],
    "sshUsername": "builderbot",
    "sshPassword": "************",
    "storageProvider": null,
    "buildOutputName": null,
    "conversionFormats": null,
    "isCloudInit": false,
    "vmToolsInstalled": true,
    "keepResults": 2,
    "config": {
      "instance": {
        "layout": {
          "code": "vmware-1.0-single",
          "id": 142
        },
        "type": "vmware",
        "userGroup": {
          "id": ""
        }
      },
      "networkInterfaces": [
        {
          "primaryInterface": true,
          "network": {
            "id": "network-147"
          }
        }
      ],
      "volumes": [
        {
          "vId": 1752,
          "size": 10,
          "maxIOPS": null,
          "name": "root",
          "rootVolume": true,
          "storageType": 1,
          "datastoreId": "auto"
        }
      ],
      "storageControllers": [

      ],
      "zoneId": 1,
      "config": {
        "template": 1752,
        "vmwareResourcePoolId": "resgroup-123",
        "expose": 8080
      },
      "plan": {
        "code": "vm-512",
        "id": 75
      }
    },
    "lastResult": {
      "id": 70,
      "imageBuild": {
        "id": 21,
        "name": "testbuild"
      },
      "buildNumber": 6,
      "startDate": "2017-09-28T05:48:03Z",
      "endDate": null,
      "statusMessage": "Booting",
      "statusPercent": 20.0,
      "statusEta": null,
      "status": "running",
      "errorMessage": null,
      "createdBy": {
        "username": "admin"
      },
      "tempInstance": null,
      "virtualImages": [

      ]
    },
    "executionCount": 4
  },
  "imageBuildExecutions": [
    {
      "id": 70,
      "imageBuild": {
        "id": 21,
        "name": "testbuild"
      },
      "buildNumber": 6,
      "startDate": "2017-09-28T05:48:03Z",
      "endDate": null,
      "statusMessage": "Booting",
      "statusPercent": 20.0,
      "statusEta": null,
      "status": "running",
      "errorMessage": null,
      "createdBy": {
        "username": "admin"
      },
      "tempInstance": null,
      "virtualImages": [

      ]
    },
    {
      "id": 57,
      "imageBuild": {
        "id": 21,
        "name": "testbuild"
      },
      "buildNumber": 3,
      "startDate": "2017-09-27T02:41:26Z",
      "endDate": "2017-09-27T03:08:30Z",
      "statusMessage": null,
      "statusPercent": 100.0,
      "statusEta": null,
      "status": "success",
      "errorMessage": null,
      "createdBy": {
        "username": "admin"
      },
      "tempInstance": null,
      "virtualImages": [
        {
          "id": 1812,
          "name": "testbuild-1-156-1506480866464"
        }
      ]
    }
  ]
}

This endpoint retrieves a specific image build.

HTTP Request

GET $serverUrl/api/image-builds/:id

URL Parameters

Parameter Description
ID The ID of the image build to retrieve

Create an Image Build

curl -XPOST "$serverUrl/api/image-builds" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "imageBuild": {
    "type": "vmware",
    "name": "builder test",
    "description": null,
    "site": {
      "id": 1
    },
    "zone": {
      "id": 1
    },
    "config": {
      "zoneId": 1,
      "instance": {
        "name": "builder test",
        "site": {
          "id": 1
        },
        "type": "vmware",
        "instanceType": {
          "code": "vmware"
        },
        "layout": {
          "id": 142
        },
        "plan": {
          "id": 76
        },
        "networkDomain": {
        }
      },
      "config": {
        "resourcePoolId": "resgroup-123",
        "template": 1232,
        "nestedVirtualization": "off",
        "expose": "8080"
      },
      "volumes": [
        {
          "id": -1,
          "rootVolume": true,
          "name": "root",
          "size": 10,
          "storageType": 1,
          "datastoreId": "autoCluster"
        }
      ],
      "networkInterfaces": [
        {
          "network": {
            "id": "network-147"
          },
          "networkInterfaceTypeId": 4
        }
      ]
    },
    "bootScript": {
      "id": 2
    },
    "preseedScript": {
      "id": 2
    },
    "scripts": [

    ],
    "sshUsername": "builderbot",
    "sshPassword": "password",
    "storageProvider": null,
    "isCloudInit": "off",
    "buildOutputName": null,
    "conversionFormats": null,
    "keepResults": 0
  }
}'

The above command returns JSON structured like getting a single image build.

HTTP Request

POST $serverUrl/api/image-builds

JSON Parameters

Parameter Default Description
name A name for the image build
description A description for the image build
type The image builder type. [vmware]
site Group
zone Cloud
config A map of config values. This is the instance config that is used for provisioning. See Provisioning Types.
bootScript Boot Script
preseedScript Preseed Script
sshUsername SSH Username
sshPassword SSH Password
storageProvider Storage Provider
isCloudInit Cloud Init
buildOutputName Build Output Name
conversionFormats Conversion Formats - ie. ovf, qcow2, vhd
keepResults 0 Keep Results - Keep only the most recent builds. Older executions will be deleted along with their associated Virtual Images. The value 0 disables this functionality.

Update an Image Build

curl -XPUT "$serverUrl/api/image-builds/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "imageBuild": {
    "description": "a good build",
    "keepResults": 5,
  }
}'

The above command returns JSON structured like getting a single image build.

HTTP Request

PUT $serverUrl/api/image-builds/1

URL Parameters

Parameter Description
ID The ID of the image build

JSON Parameters

See Create.

Delete an Image Build

curl -XDELETE "$serverUrl/api/image-builds/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete an image build from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/image-builds/:id

URL Parameters

Parameter Description
ID The ID of the image build

Run an Image Build

curl -XPOST "$serverUrl/api/image-builds/1/run" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true
}

Running an image build is done asynchronously. This api will kick off the new execution and update the image build status.

HTTP Request

POST $serverUrl/api/image-builds/1/run

URL Parameters

Parameter Description
ID The ID of the image build

List Image Build Executions

curl "$serverUrl/api/image-builds/1/list-executions" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "imageBuildExecutions": [
    {
      "id": 82,
      "imageBuild": {
        "id": 20,
        "name": "my-testbuild"
      },
      "buildNumber": 2,
      "startDate": "2017-09-29T15:30:07Z",
      "endDate": null,
      "statusMessage": "Installing",
      "statusPercent": 25.0,
      "statusEta": null,
      "status": "running",
      "errorMessage": null,
      "createdBy": {
        "username": "admin"
      },
      "tempInstance": null,
      "virtualImages": [

      ]
    },
    {
      "id": 81,
      "imageBuild": {
        "id": 20,
        "name": "my-testbuild"
      },
      "buildNumber": 1,
      "startDate": "2017-09-29T14:57:33Z",
      "endDate": "2017-09-29T15:26:41Z",
      "statusMessage": null,
      "statusPercent": 100.0,
      "statusEta": null,
      "status": "success",
      "errorMessage": null,
      "createdBy": {
        "username": "admin"
      },
      "tempInstance": null,
      "virtualImages": [
        {
          "id": 1850,
          "name": "my-testbuild-4-176-1506697891084"
        }
      ]
    }
  ],
  "imageBuildExecutionCount": 2,
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

List all executions for an image build. This same info is also returned by the image build GET api, which returns the 100 most recent executions.

HTTP Request

GET $serverUrl/api/image-builds/1/list-executions

URL Parameters

Parameter Description
ID The ID of the image build

Query Parameters

Parameter Default Description
buildNumber If specified will return an exact match on buildNumber
status Filter by status [running, success, failed]

Boot Scripts

Boot Scripts are used in the Image Builder service. See Image Builds

curl "$serverUrl/api/boot-scripts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "bootScripts": [
    {
      "id": 1,
      "account": {
        "id": 1,
        "name": "root"
      },
      "fileName": "debian standard",
      "description": null,
      "content": "...",
      "createdBy": {
        "username": "admin"
      },
      "visibility": "private"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all boot scripts associated with the account.

HTTP Request

GET $serverUrl/api/boot-scripts

Query Parameters

Parameter Default Description
name If specified will return an exact match on fileName
phrase If specified will return a partial match on fileName

Get a Specific Boot Script

curl "$serverUrl/api/boot-scripts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "bootScript": {
    "id": 1,
    "account": {
      "id": 1,
      "name": "root"
    },
    "fileName": "debian standard",
    "description": null,
    "content": "...",
    "createdBy": {
      "username": "admin"
    },
    "visibility": "private"
  }
}

This endpoint retrieves a specific boot script.

HTTP Request

GET $serverUrl/api/boot-scripts/:id

URL Parameters

Parameter Description
ID The ID of the boot script to retrieve

Create a Boot Script

curl -XPOST "$serverUrl/api/boot-scripts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "bootScript": {
    "fileName": "debian standard",
    "content": "<esc><wait>install <wait> preseed/url=<%=preseedUrl%> <wait>debian-installer=en_US.UTF-8 <wait>auto <wait>locale=en_US.UTF-8 <wait>kbd-chooser/method=us <wait>keyboard-configuration/xkb-keymap=us <wait>netcfg/get_hostname=<%=container.hostname%> <wait>netcfg/get_domain=morpheusdata.com <wait>fb=false <wait>debconf/frontend=noninteractive <wait>console-setup/ask_detect=false <wait>console-keymaps-at/keymap=us <wait>grub-installer/bootdev=/dev/sda <wait><enter><wait>"
  }
}'

The above command returns JSON structured like getting a single boot script:

HTTP Request

POST $serverUrl/api/boot-scripts

JSON Parameters

Parameter Default Description
fileName A name for the boot script
content The script content

Update a Boot Script

curl -XPUT "$serverUrl/api/boot-scripts/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "bootScript": {
    "fileName": "debian default"
  }
}'

The above command returns JSON structured like getting a single boot script:

HTTP Request

PUT $serverUrl/api/boot-scripts/1

URL Parameters

Parameter Description
ID The ID of the boot script

JSON Parameters

Same as Create.

Delete a Boot Script

curl -XDELETE "$serverUrl/api/boot-scripts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a boot script from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/boot-scripts/:id

URL Parameters

Parameter Description
ID The ID of the boot script

Preseed Scripts

Preseed Scripts are used in the Image Builder service. See Image Builds

curl "$serverUrl/api/preseed-scripts"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "preseedScripts": [
    {
      "id": 1,
      "account": {
        "id": 1,
        "name": "root"
      },
      "fileName": "debian 8",
      "description": null,
      "content": "...",
      "createdBy": {
        "username": "admin"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all preseed scripts associated with the account.

HTTP Request

GET $serverUrl/api/preseed-scripts

Query Parameters

Parameter Default Description
name If specified will return an exact match on fileName
phrase If specified will return a partial match on fileName

Get a Specific Preseed Script

curl "$serverUrl/api/preseed-scripts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "preseedScript": {
    "id": 1,
    "account": {
      "id": 1,
      "name": "root"
    },
    "fileName": "debian 8",
    "description": null,
    "content": "...",
    "createdBy": {
      "username": "admin"
    }
  }
}

This endpoint retrieves a specific preseed script.

HTTP Request

GET $serverUrl/api/preseed-scripts/:id

URL Parameters

Parameter Description
ID The ID of the preseed script to retrieve

Create a Preseed Script

curl -XPOST "$serverUrl/api/preseed-scripts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "preseedScript": {
    "fileName": "ubuntu build",
    "content": "choose-mirror-bin mirror/http/proxy string\nd-i apt-setup/use_mirror boolean true\nd-i base-installer/kernel/override-image string linux-server\nd-i debian-installer/add-kernel-opts string net.ifnames=0 biosdevname=0\nd-i clock-setup/utc boolean true\nd-i clock-setup/utc-auto boolean true\nd-i finish-install/reboot_in_progress note\nd-i grub-installer/only_debian boolean true\nd-i grub-installer/with_other_os boolean true\nd-i keymap select us\nd-i mirror/country string manual\nd-i mirror/http/directory string /debian\nd-i mirror/http/hostname string httpredir.debian.org\nd-i mirror/http/proxy string\n# Alternatively, you may specify a disk to partition. If the system has only\n# one disk the installer will default to using that, but otherwise the device\n# name must be given in traditional, non-devfs format (so e.g. /dev/sda\n# and not e.g. /dev/discs/disc0/disc).\n# For example, to use the first SCSI/SATA hard disk:\n#d-i partman-auto/disk string /dev/sda\n# In addition, you'll need to specify the method to use.\n# The presently available methods are:\n# - regular: use the usual partition types for your architecture\n# - lvm:     use LVM to partition the disk\n# - crypto:  use LVM within an encrypted partition\nd-i partman-auto/method string regular\n\n# If one of the disks that are going to be automatically partitioned\n# contains an old LVM configuration, the user will normally receive a\n# warning. This can be preseeded away...\nd-i partman-lvm/device_remove_lvm boolean true\n# The same applies to pre-existing software RAID array:\nd-i partman-md/device_remove_md boolean true\n# And the same goes for the confirmation to write the lvm partitions.\nd-i partman-lvm/confirm boolean true\nd-i partman-lvm/confirm_nooverwrite boolean true\n\n# For LVM partitioning, you can select how much of the volume group to use\n# for logical volumes.\n#d-i partman-auto-lvm/guided_size string max\n#d-i partman-auto-lvm/guided_size string 10GB\n#d-i partman-auto-lvm/guided_size string 50%\n\n# You can choose one of the three predefined partitioning recipes:\n# - atomic: all files in one partition\n# - home:   separate /home partition\n# - multi:  separate /home, /var, and /tmp partitions\nd-i partman-auto/choose_recipe select atomic\nd-i partman-basicfilesystems/no_swap boolean false\nd-i partman-auto/expert_recipe string \\\n    single-root :: \\\n\t\t  1000 50 -1 ext4 \\\n      $primary{ } \\\n\t\t\t$bootable{ } \\\n\t\t\tmethod{ format } \\\n      format{ } \\\n\t\t\tuse_filesystem{ } \\\n\t\t\tfilesystem{ ext4 } \\\n      mountpoint{ / } .\nd-i partman-auto/choose_recipe select single-root\nd-i partman/mount_style select uuid\nd-i partman/choose_partition select finish\nd-i partman/confirm boolean true\nd-i partman/confirm_nooverwrite boolean true\nd-i partman/confirm_write_new_label boolean true\nd-i passwd/root-login boolean false\nd-i passwd/root-password-again password password\nd-i passwd/root-password password password\nd-i passwd/user-fullname string builderbot\nd-i passwd/user-uid string 1000\nd-i passwd/user-password password password\nd-i passwd/user-password-again password password\nd-i passwd/username string builderbot\nd-i pkgsel/include string openssh-server cryptsetup build-essential libssl-dev libreadline-dev zlib1g-dev linux-source dkms nfs-common open-vm-tools\nd-i pkgsel/install-language-support boolean false\nd-i pkgsel/update-policy select none\nd-i pkgsel/upgrade select full-upgrade\n# Prevent packaged version of VirtualBox Guest Additions being installed:\nd-i preseed/early_command string sed -i \\\n  '/in-target/idiscover(){/sbin/discover|grep -v VirtualBox;}' \\\n  /usr/lib/pre-pkgsel.d/20install-hwpackages\nd-i time/zone string UTC\nd-i user-setup/allow-password-weak boolean true\nd-i user-setup/encrypt-home boolean false\nd-i preseed/late_command string sed -i '/^deb cdrom:/s/^/#/' /target/etc/apt/sources.list\napt-cdrom-setup apt-setup/cdrom/set-first boolean false\napt-mirror-setup apt-setup/use_mirror boolean true\npopularity-contest popularity-contest/participate boolean false\ntasksel tasksel/first multiselect standard, ssh-server"
  }
}'

The above command returns JSON structured like getting a single preseed script:

HTTP Request

POST $serverUrl/api/preseed-scripts

JSON Parameters

Parameter Default Description
fileName A name for the preseed script
content The script content

Update a Preseed Script

curl -XPUT "$serverUrl/api/preseed-scripts/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "preseedScript": {
    "fileName": "good ubuntu"
  }
}'

The above command returns JSON structured like getting a single preseed script:

HTTP Request

PUT $serverUrl/api/preseed-scripts/1

URL Parameters

Parameter Description
ID The ID of the preseed script

JSON Parameters

See Create.

Delete a Preseed Script

curl -XDELETE "$serverUrl/api/preseed-scripts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a preseed script from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/preseed-scripts/:id

URL Parameters

Parameter Description
ID The ID of the preseed script

Self Service

Provides API interfaces for the Tools: Self Service functionality, which involves viewing and managing catalog item types. These are the types that become available for order by the Service Catalog persona.

This is the adminstrative api for the Tools: Self Service functionality.

Get All Catalog Item Types

curl "$serverUrl/api/catalog-item-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "catalogItemTypes": [
    {
      "id": 1,
      "name": "Example Instance",
      "description": "Example catalog item type",
      "type": "instance",
      "blueprint": null,
      "refType": "InstanceType",
      "refId": null,
      "active": true,
      "enabled": true,
      "featured": true,
      "iconPath": "/assets/containers-png/nginx.png",
      "config": {
        "group": {
          "id": 20,
          "name": "Example Group"
        },
        "cloud": {
          "id": 8,
          "name": "Example Cloud"
        },
        "type": "nginx",
        "name": "${userInitials}-${cloudCode}-${type}-simple-${sequence}",
        "hostName": "${userInitials}-${cloudCode}-${type}-simple-${sequence}",
        "layout": {
          "id": 7342,
          "code": "nginx-1.14-single"
        },
        "plan": {
          "id": 68,
          "code": "container-128"
        },
        "version": "1.9",
        "config": {
          "createUser": true,
          "resourcePoolId": 94944,
        },
        "networkInterfaces": [
          {
            "network": {
              "id": "network-3",
            }
          }
        ],
        "volumes": [
          {
            "rootVolume": true,
            "name": "root",
            "size": 60,
          }
        ]
      },
      "optionTypes": [

      ],
      "createdBy": null,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "dateCreated": "2020-09-09T23:35:47Z",
      "lastUpdated": "2020-09-16T03:58:32Z"
    },
        {
      "id": 2,
      "name": "Example App",
      "description": "Example catalog item type using a blueprint with scribe",
      "type": "blueprint",
      "blueprint": {
        "id": 15,
        "name": "Example Blueprint"
      },
      "refType": "AppTemplate",
      "refId": null,
      "active": true,
      "enabled": true,
      "featured": true,
      "iconPath": "/assets/containers-png/docker.png",
      "appSpec": "name: <%= customOptions.appName %>\r\ngroup:\r\n  name: Example\r\nenvironment: Test\r\ntiers:\r\n  Web:\r\n    instances:\r\n      - instance:\r\n          type: nginx\r\n          cloud: Example\r\n  App:\r\n    instances:\r\n      - instance:\r\n          type: activemq\r\n          cloud: Example",
      "optionTypes": [
        {
          "id": 2926,
          "name": "App Name",
          "description": "Enter a unique name for the app",
          "code": "appName",
          "fieldName": "appName",
          "fieldLabel": "App Name",
          "fieldCode": null,
          "fieldContext": "config.customOptions",
          "fieldGroup": null,
          "fieldClass": null,
          "fieldAddOn": null,
          "fieldComponent": null,
          "fieldInput": null,
          "placeHolder": null,
          "verifyPattern": null,
          "helpBlock": null,
          "defaultValue": null,
          "optionSource": null,
          "optionList": null,
          "type": "text",
          "advanced": false,
          "required": true,
          "exportMeta": false,
          "editable": false,
          "creatable": true,
          "config": {
          },
          "displayOrder": 0,
          "wrapperClass": null,
          "enabled": true,
          "noBlank": false,
          "dependsOnCode": null,
          "contextualDefault": false
        }
      ],
      "createdBy": null,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "dateCreated": "2020-09-25T19:13:05Z",
      "lastUpdated": "2020-09-28T20:29:55Z"
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "max": 25,
    "offset": 25
  }
}

This endpoint retrieves all catalog item types.

HTTP Request

GET $serverUrl/api/catalog-item-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%
description Filter by description, wildcard may be specified as %. eg. example-%
enabled Filter by enabled, eg. true or false
featured Filter by featured, eg. true or false

Get a Specific Catalog Item Type

curl "$serverUrl/api/catalog-item-types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "catalogItemType": {
    "id": 1,
    "name": "Example Nginx",
    "description": "Example catalog item for an nginx instance",
    "type": "instance",
    "blueprint": null,
    "refType": "InstanceType",
    "refId": null,
    "active": true,
    "enabled": true,
    "featured": true,
    "iconPath": "/assets/containers-png/resource.png",
    "config": {
      "group": {
        "id": 20,
        "name": "Example Group"
      },
      "cloud": {
        "id": 8,
        "name": "Example Cloud"
      },
      "type": "nginx",
      "name": "${userInitials}-${cloudCode}-${type}-simple-${sequence}",
      "hostName": "${userInitials}-${cloudCode}-${type}-simple-${sequence}",
      "layout": {
        "id": 7342,
        "code": "nginx-1.14-single"
      },
      "plan": {
        "id": 68,
        "code": "container-128"
      },
      "version": "1.9",
      "config": {
        "createUser": true,
        "resourcePoolId": 94944,
      },
      "volumes": [
        {
          "rootVolume": true,
          "name": "root",
          "size": 60,
        }
      ]
    },
    "optionTypes": [

    ],
    "createdBy": null,
    "owner": {
      "id": 1,
      "name": "root"
    },
    "dateCreated": "2020-09-09T23:35:47Z",
    "lastUpdated": "2020-09-16T03:58:32Z"
  }
}

This endpoint retrieves a specific category item type.

HTTP Request

GET $serverUrl/api/catalog-item-types/:id

URL Parameters

Parameter Description
id ID of the Catalog Item Type

Create a Catalog Item Type

curl -XPOST "$serverUrl/api/catalog-item-types" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "catalogItemType": {
    "name": "Example App",
    "description": "Example catalog item type",
    "type": "instance",
    "iconPath": "/assets/containers-png/apache.png",
    "config": {
      "group": {
        "id": "<%= customOptions.morphgroup %>"
      },
      "cloud": {
        "id": "<%= customOptions.morphcloud %>"
      },
      "type": "apache",
      "instance": {
      },
      "name": "${userInitials}-apache-${sequence}",
      "config": {
        "createUser": true,
        "resourcePoolId": "<%= customOptions.morphpool %>"
      },
      "environment": "<%= customOptions.morphenv %>",
      "volumes": [
        {
          "rootVolume": true,
          "name": "root",
          "size": 10,
          "storageType": 5
        }
      ],
      "hostName": "${userInitials}-apache-${sequence}",
      "layout": {
        "id": 31,
        "code": "apache-amazon-2.4-single"
      },
      "networkInterfaces": [
        {
          "primaryInterface": true,
          "network": {
            "id": "<%= customOptions.morphnetwork %>",
            "hasPool": false
          },
          "ipMode": "",
          "showNetworkPoolLabel": false,
          "showNetworkDhcpLabel": true
        }
      ],
      "plan": {
        "id": "<%= customOptions.morphplan %>"
      },
      "version": "2.4",
      "securityGroups": [
        {
          "id": "<%= customOptions.morphsecgroup %>"
        }
      ]
    },
    "optionTypes": [
      34,35,36,37,38,39,40
    ]
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "catalogItemType": {
    "id": 1
  }
}

Use this command to create a catalog item type.

HTTP Request

POST $serverUrl/api/catalog-item-types

JSON Parameters

Parameter Required Description
name Y Catalog Item Type name
description N Catalog Item Type description
type N Type, instance, blueprint or workflow. This determines whether an Instance or App will be provisioned. Instance types require a config and blueprint requires a blueprint and appSpec, while workflow types requires a workflow and context.
iconPath N Icon Path, relative location of an icon image, eg. /assets/containers-png/nginx.png.
logo N Logo File png,jpg,svg Only available when using multipart form data content instead of JSON
enabled N Can be used to enable / disable the catalog item type. Default is true
featured N Can be used to feature the catalog item type. Default is false
optionTypes N Array of option type IDs, see Option Types. Only applies to type instance and blueprint. The workflow type always uses the option types from the workflow and its tasks instead.
config Y Config Object, see Catalog Config For Instance
blueprint Y Blueprint object, identified by id or name. Only applies to type blueprint
appSpec Y App Spec YAML, see App Spec For Blueprint. Only applies to type blueprint
workflow Y Operational Workflow object, identified by id or name. Only applies to type workflow
context N Context for running the workflow, determines if a resource must be selected. instance,server, or appliance.

Catalog Config For Instance

The config for instance type catalog items is an object with fields:

Parameter Required Description
name Y Name of instance
group Y Group, id or name of the group to associate the instance with
cloud Y Cloud, id or name of the cloud being provisioned into
type Y Instance Type, id or code for the type of instance eg. nginx
layout Y Layout, id or code for the instance type that you want to provision. i.e. single process or cluster
plan Y Plan, id or code for the memory and storage option

For the full list of instance provisioning options, see Create an Instance

App Spec For Blueprint

The appSpec for blueprint type catalog items is a string in the Scribe YAML format with fields:

Parameter Required Description
name N Name of the app
group N Name of group
environment N Name of environment
tiers N Object with each key is a tier name and its value is the tier configuration, including an array of instances, each with their own type and settings.

Create a Catalog Item Type For Blueprint

curl -XPOST "$serverUrl/api/catalog-item-types" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "catalogItemType": {
    "name": "Example App",
    "description": "Example catalog item type",
    "type": "blueprint",
    "iconPath": "/assets/containers-png/resource.png",
    "blueprint": {
      "id": 13278
    },
    "appSpec": "name: <%= customOptions.appName %>\r\ngroup:\r\n  name: Example\r\nenvironment: Test\r\ntiers:\r\n  Web:\r\n    instances:\r\n      - instance:\r\n          type: nginx\r\n          cloud: Example\r\n  App:\r\n    instances:\r\n      - instance:\r\n          type: apache\r\n          cloud: Example",
    "optionTypes": [
      2926
    ]
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "catalogItemType": {
    "id": 1
  }
}

Use this command to create a catalog item type for a blueprint. This type uses the specified blueprint and appSpec to provision an App.

HTTP Request

POST $serverUrl/api/catalog-item-types

JSON Parameters

See Create.

Create a Catalog Item Type For Workflow

curl -XPOST "$serverUrl/api/catalog-item-types" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "catalogItemType": {
    "name": "Example Operation",
    "description": "Example catalog item type",
    "type": "workflow",
    "workflow": {
      "id": 13
    },
    "context": "instance"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "catalogItemType": {
    "id": 1
  }
}

Use this command to create a catalog item type for a workflow. This type uses the specified workflow and context to execute an Operation Workflow(#workflows). This type cannot be configured with its own option types, they come from the workflow and its tasks instead.

HTTP Request

POST $serverUrl/api/catalog-item-types

JSON Parameters

See Create.

Update a Catalog Item Type

curl -XPUT "$serverUrl/api/catalog-item-types/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "catalogItemType": {
    "featured": true
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

Use this command to update an existing catalog item type.

HTTP Request

PUT $serverUrl/api/catalog-item-types/:id

URL Parameters

Parameter Description
id The ID of the catalog item type

JSON Parameters

Parameter Required Description
name Y Catalog Item Type name
description N Catalog Item Type description
iconPath N Icon Path, relative location of an icon image, eg. /assets/containers-png/nginx.png.
logo N Logo File png,jpg,svg Only available when using multipart form data content instead of JSON
enabled N Can be used to enable / disable the catalog item type. Default is true
featured N Can be used to feature the catalog item type. Default is false
optionTypes N Array of layout option type IDs, see Option Types
config Y Config Object, see Catalog Config For Instance
blueprint Y Blueprint object, identified by id or name. Only applies to type: blueprint
appSpec Y App Spec YAML, see App Spec For Blueprint. Only applies to type: blueprint
workflow Y Operational Workflow object, identified by id or name. Only applies to type: workflow
context N Context for running the workflow, determines if a target resource must be selected. instance,server, or appliance.

Update Logo For Catalog Item Type

curl -XPUT "$serverUrl/api/catalog-item-types/:id" \
  -H "Authorization: BEARER $accessToken"
  -F 'catalogItemType.logo=@filename'

The above command returns JSON structured like this:

{
  "success": true
}

Use this command to update the logo image for an existing catalog item type. This endpoint expects multipart form data as the request format, not JSON.

HTTP Request

PUT $serverUrl/api/catalog-item-types/:id

URL Parameters

Parameter Description
id The ID of the catalog item type

Parameters

Parameter Default Description
catalogItemType.logo Logo File png,jpg,svg

Delete a Catalog Item Type

curl -XDELETE "$serverUrl/api/catalog-item-types/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a catalog item type.

HTTP Request

DELETE $serverUrl/api/catalog-item-types/:id

URL Parameters

Parameter Description
id The ID of the catalog item type

VDI Pools

Provides API interfaces for the Tools: VDI Pools functionality, which involves viewing and managing VDI Pools, Apps and Gateways. VDI Pools are the virtual desktops that become available for allocation and use by the Virtual Desktop Persona.

List VDI Pools

curl "$serverUrl/api/vdi-pools" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "vdiPools": [
    {
      "id": 1,
      "name": "Windows Desktop",
      "description": "A fancy windows desktop",
      "minIdle": 0,
      "maxIdle": 0,
      "initialPoolSize": 0,
      "maxPoolSize": 5,
      "allocationTimeoutMinutes": 60,
      "persistentUser": false,
      "recyclable": false,
      "enabled": true,
      "autoCreateLocalUserOnReservation": false,
      "allowHypervisorConsole": false,
      "allowCopy": false,
      "allowPrinter": false,
      "allowFileshare": false,
      "guestConsoleJumpHost": null,
      "guestConsoleJumpPort": null,
      "guestConsoleJumpUsername": null,
      "guestConsoleJumpPassword": null,
      "guestConsoleJumpKeypair": null,
      "gateway": null,
      "iconPath": "/assets/containers-png/morph-resource2.png",
      "logo": "/assets/containers-png/morph-resource2.png",
      "apps": [
        {
          "id": 1,
          "name": "Notepad"
        }
      ],
      "owner": {
        "id": 1,
        "name": "Admin",
        "username": "admin"
      },
      "config": {
        "group": {
          "id": 1,
          "name": "dev"
        },
        "cloud": {
          "id": 34,
          "name": "vmware"
        },
        "type": "windows",
        "config": {
          "isEC2": false,
          "isVpcSelectable": true,
          "noAgent": false,
          "resourcePoolId": 3551
        },
        "name": "vdi-example-${sequence}",
        "volumes": [
          {
            "name": "root",
            "rootVolume": true,
            "typeId": 1,
            "size": 16,
            "storageType": 1,
            "datastoreId": "auto"
          }
        ],
        "hostName": "vdi-example-${sequence}",
        "layout": {
          "id": 250,
          "code": "vmware-windows-2012_r2-single"
        },
        "networkInterfaces": [
          {
            "primaryInterface": true,
            "network": {
              "id": "network-1482"
            },
            "networkInterfaceTypeId": 4,
            "networkInterfaceTypeIdName": "VMXNET 3"
          }
        ],
        "plan": {
          "id": 75,
          "code": "vm-512"
        },
        "version": "2012 r2"
      },
      "group": {
        "id": 1,
        "name": "dev"
      },
      "cloud": {
        "id": 34,
        "name": "vmware"
      },
      "usedCount": 0,
      "reservedCount": 0,
      "preparingCount": 0,
      "idleCount": 0,
      "status": "available",
      "dateCreated": "2021-04-13T14:45:25Z",
      "lastUpdated": "2021-04-13T14:45:25Z"
    },
    {
      "id": 2,
      "name": "Test Desktop",
      "description": "Our test machine",
      "minIdle": 0,
      "maxIdle": 0,
      "initialPoolSize": 0,
      "maxPoolSize": 1,
      "allocationTimeoutMinutes": 360,
      "persistentUser": false,
      "recyclable": false,
      "enabled": true,
      "autoCreateLocalUserOnReservation": false,
      "allowHypervisorConsole": false,
      "allowCopy": false,
      "allowPrinter": false,
      "allowFileshare": false,
      "guestConsoleJumpHost": null,
      "guestConsoleJumpPort": null,
      "guestConsoleJumpUsername": null,
      "guestConsoleJumpPassword": null,
      "guestConsoleJumpKeypair": null,
      "gateway": null,
      "iconPath": "/assets/containers-png/morph-resource2.png",
      "logo": "/assets/containers-png/morph-resource2.png",
      "apps": [

      ],
      "owner": {
        "id": 1,
        "name": "Admin",
        "username": "admin"
      },
      "config": {
        "group": {
          "id": 1,
          "name": "dev"
        },
        "cloud": {
          "id": 34,
          "name": "vmware"
        },
        "type": "windows",
        "config": {
          "isEC2": false,
          "isVpcSelectable": true,
          "noAgent": false,
          "resourcePoolId": 3551
        },
        "name": "vdi-test-${sequence}",
        "volumes": [
          {
            "name": "root",
            "rootVolume": true,
            "typeId": 1,
            "size": 16,
            "storageType": 1,
            "datastoreId": "auto"
          }
        ],
        "hostName": "vdi-test-${sequence}",
        "layout": {
          "id": 250,
          "code": "vmware-windows-2012_r2-single"
        },
        "networkInterfaces": [
          {
            "primaryInterface": true,
            "network": {
              "id": "network-1482"
            },
            "networkInterfaceTypeId": 4,
            "networkInterfaceTypeIdName": "VMXNET 3"
          }
        ],
        "plan": {
          "id": 75,
          "code": "vm-512"
        },
        "version": "2012 r2"
      },
      "group": {
        "id": 1,
        "name": "dev"
      },
      "cloud": {
        "id": 34,
        "name": "vmware"
      },
      "usedCount": 1,
      "reservedCount": 1,
      "preparingCount": 0,
      "idleCount": 0,
      "status": "available",
      "dateCreated": "2021-03-30T03:10:40Z",
      "lastUpdated": "2021-03-30T03:45:36Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all VDI Pools.

HTTP Request

GET $serverUrl/api/vdi-pools

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%
description Filter by description, wildcard may be specified as %. eg. example-%
enabled Filter by enabled, eg. true or false

Get a Specific VDI Pool

curl "$serverUrl/api/vdi-pools/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "vdiPool": {
      "id": 1,
      "name": "Windows Desktop",
      "description": "A fancy windows desktop",
      "minIdle": 0,
      "maxIdle": 0,
      "initialPoolSize": 0,
      "maxPoolSize": 5,
      "allocationTimeoutMinutes": 60,
      "persistentUser": false,
      "recyclable": false,
      "enabled": true,
      "autoCreateLocalUserOnReservation": false,
      "allowHypervisorConsole": false,
      "allowCopy": false,
      "allowPrinter": false,
      "allowFileshare": false,
      "guestConsoleJumpHost": null,
      "guestConsoleJumpPort": null,
      "guestConsoleJumpUsername": null,
      "guestConsoleJumpPassword": null,
      "guestConsoleJumpKeypair": null,
      "gateway": null,
      "iconPath": "/assets/containers-png/morph-resource2.png",
      "logo": "/assets/containers-png/morph-resource2.png",
      "apps": [
        {
          "id": 1,
          "name": "Notepad"
        }
      ],
      "owner": {
        "id": 1,
        "name": "Admin",
        "username": "admin"
      },
      "config": {
        "group": {
          "id": 1,
          "name": "dev"
        },
        "cloud": {
          "id": 34,
          "name": "vmware"
        },
        "type": "windows",
        "config": {
          "isEC2": false,
          "isVpcSelectable": true,
          "noAgent": false,
          "resourcePoolId": 3551
        },
        "name": "vdi-example-${sequence}",
        "volumes": [
          {
            "name": "root",
            "rootVolume": true,
            "typeId": 1,
            "size": 16,
            "storageType": 1,
            "datastoreId": "auto"
          }
        ],
        "hostName": "vdi-example-${sequence}",
        "layout": {
          "id": 250,
          "code": "vmware-windows-2012_r2-single"
        },
        "networkInterfaces": [
          {
            "primaryInterface": true,
            "network": {
              "id": "network-1482"
            },
            "networkInterfaceTypeId": 4,
            "networkInterfaceTypeIdName": "VMXNET 3"
          }
        ],
        "plan": {
          "id": 75,
          "code": "vm-512"
        },
        "version": "2012 r2"
      },
      "group": {
        "id": 1,
        "name": "dev"
      },
      "cloud": {
        "id": 34,
        "name": "vmware"
      },
      "usedCount": 0,
      "reservedCount": 0,
      "preparingCount": 0,
      "idleCount": 0,
      "status": "available",
      "dateCreated": "2021-04-13T14:45:25Z",
      "lastUpdated": "2021-04-13T14:45:25Z"
    }
}

This endpoint retrieves a specific VDI Pool.

HTTP Request

GET $serverUrl/api/vdi-pools/:id

URL Parameters

Parameter Description
id ID of the VDI Pool

Create a VDI Pool

curl -XPOST "$serverUrl/api/vdi-pools" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "vdiPool": {
    "name": "Windows Desktop",
    "description": "A fancy windows desktop",
    "owner": 1,
    "minIdle": 0,
    "initialPoolSize": 0,
    "maxIdle": 0,
    "maxPoolSize": 5,
    "allocationTimeoutMinutes": 60,
    "persistentUser": false,
    "recyclable": false,
    "allowCopy": false,
    "allowPrinter": false,
    "allowFileshare": false,
    "allowHypervisorConsole": false,
    "autoCreateLocalUserOnReservation": false,
    "enabled": true,
    "iconPath": "/assets/containers-png/windows.png",
    "apps": [
      1
    ],
    "gateway": null,
    "instanceConfig": "{\n  \"group\": {\n    \"id\": \"1\",\n    \"name\": \"dev\"\n  },\n  \"cloud\": {\n    \"id\": 34,\n    \"name\": \"vmware\"\n  },\n  \"type\": \"windows\",\n  \"config\": {\n    \"isEC2\": false,\n    \"isVpcSelectable\": true,\n    \"noAgent\": false,\n    \"resourcePoolId\": 3551\n  },\n  \"name\": \"desktop-example-${sequence}\",\n  \"volumes\": [\n    {\n      \"name\": \"root\",\n      \"rootVolume\": true,\n      \"typeId\": 1,\n      \"size\": 16,\n      \"storageType\": 1,\n      \"datastoreId\": \"auto\"\n    }\n  ],\n  \"hostName\": \"desktop-example-${sequence}\",\n  \"layout\": {\n    \"id\": 250,\n    \"code\": \"vmware-windows-2012_r2-single\"\n  },\n  \"networkInterfaces\": [\n    {\n      \"primaryInterface\": true,\n      \"network\": {\n        \"id\": \"network-1482\"      },\n      \"networkInterfaceTypeId\": 4,\n      \"networkInterfaceTypeIdName\": \"VMXNET 3\"\n    }\n  ],\n  \"plan\": {\n    \"id\": 75,\n    \"code\": \"vm-512\"\n  },\n  \"version\": \"2012 r2\"\n}"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "vdiPool": {
    "id": 1,
    "name": "Windows Desktop",
    "description": "A fancy windows desktop",
    "minIdle": 0,
    "maxIdle": 0,
    "initialPoolSize": 0,
    "maxPoolSize": 5,
    "allocationTimeoutMinutes": 60,
    "persistentUser": false,
    "recyclable": false,
    "enabled": true,
    "autoCreateLocalUserOnReservation": false,
    "allowHypervisorConsole": false,
    "allowCopy": false,
    "allowPrinter": false,
    "allowFileshare": false,
    "guestConsoleJumpHost": null,
    "guestConsoleJumpPort": null,
    "guestConsoleJumpUsername": null,
    "guestConsoleJumpPassword": null,
    "guestConsoleJumpKeypair": null,
    "gateway": null,
    "iconPath": "/assets/containers-png/morph-resource2.png",
    "logo": "/assets/containers-png/morph-resource2.png",
    "apps": [
      {
        "id": 1,
        "name": "Notepad"
      }
    ],
    "owner": {
      "id": 1,
      "name": "Admin",
      "username": "admin"
    },
    "config": {
      "group": {
        "id": 1,
        "name": "dev"
      },
      "cloud": {
        "id": 34,
        "name": "vmware"
      },
      "type": "windows",
      "config": {
        "isEC2": false,
        "isVpcSelectable": true,
        "noAgent": false,
        "resourcePoolId": 3551
      },
      "name": "vdi-example-${sequence}",
      "volumes": [
        {
          "name": "root",
          "rootVolume": true,
          "typeId": 1,
          "size": 16,
          "storageType": 1,
          "datastoreId": "auto"
        }
      ],
      "hostName": "vdi-example-${sequence}",
      "layout": {
        "id": 250,
        "code": "vmware-windows-2012_r2-single"
      },
      "networkInterfaces": [
        {
          "primaryInterface": true,
          "network": {
            "id": "network-1482"
          },
          "networkInterfaceTypeId": 4,
          "networkInterfaceTypeIdName": "VMXNET 3"
        }
      ],
      "plan": {
        "id": 75,
        "code": "vm-512"
      },
      "version": "2012 r2"
    },
    "group": {
      "id": 1,
      "name": "dev"
    },
    "cloud": {
      "id": 34,
      "name": "vmware"
    },
    "usedCount": 0,
    "reservedCount": 0,
    "preparingCount": 0,
    "idleCount": 0,
    "status": "available",
    "dateCreated": "2021-04-13T14:45:25Z",
    "lastUpdated": "2021-04-13T14:45:25Z"
  }
}

This endpoint creates a new VDI Pool. Instances will be provisioned right away if the pool is enabled and has an initialPoolSize greater than 0.

HTTP Request

POST $serverUrl/api/vdi-pools

JSON Parameters

Parameter Required Default Description
name Y Virtual Desktop name
description N Virtual Desktop description
owner N (current user) Owner (User) ID
minIdle N 0 Min Idle - Sets the minimum number of idle instances on standby in the pool. The pool will always try to maintain this number of available instances on standby.
initialPoolSize N 0 Initial Pool Size - The initial size of the pool to be allocated on creation.
maxIdle N 0 Max Idle - Sets the maximum number of idle instances on standby in the pool. If the number of idle instances supersedes this, the pool will start removing instances
maxPoolSize Y Max Size - Max limit on number of allocations and instances within the pool.
allocationTimeoutMinutes N 0 Lease Timeout - Time (in minutes) after a user disconnects before an allocation is recycled or shutdown depending on persistence.
persistentUser N N Persistent User
recyclable N N Recyclable. Recyclable VDI Pools only work with cloud types that support snapshot management (i.e. Vmware, Nutanix, VCD)
allowCopy N Allow Copy
allowPrinter N Allow Printer
allowFileshare N Allow File Share
allowHypervisorConsole N Allow Hypervisor Console
autoCreateLocalUserOnReservation N Auto Create Local User Upon Reservation
enabled N Y Can be used to enable / disable the VDI pool. Default is true
iconPath N Icon Path, relative location of an icon image, eg. /assets/containers-png/windows.png.
logo N Logo File, upload a custom logo, requires Content-Type: multipart/form-data
apps N Array of VDI App IDs, see VDI App.
gateway N VDI Gateway ID, see VDI Gateway.
instanceConfig Y Instance Config JSON, see VDI Pool Instance Config. Passing as a string will preserve property order.
config N Config Object, see VDI Pool Instance Config. This can be passed in place of instanceConfig, but will not preserve the config property order.
guestConsoleJumpHost N Guest Console Jump Host
guestConsoleJumpPort N Guest Console Jump Port
guestConsoleJumpUsername N Guest Console Jump Username
guestConsoleJumpPassword N Guest Console Jump Password
guestConsoleJumpKeypair N Guest Console Jump Key Pair. see Key Pair

VDI Pool Instance Config

The instanceConfig (string) or config (object) with fields:

Parameter Required Description
name Y Name of instance
group Y Group, id or name of the group to associate the instance with
cloud Y Cloud, id or name of the cloud being provisioned into
type Y Instance Type, id or code for the type of instance eg. nginx
layout Y Layout, id or code for the instance type that you want to provision. i.e. single process or cluster
plan Y Plan, id or code for the memory and storage option

For the full list of instance provisioning options, see Create an Instance

Update a VDI Pool

curl -XPUT "$serverUrl/api/vdi-pools/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "vdiPool": {
    "maxPoolSize": 10
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint updates an existing VDI Pool. Instance may be provisioned or removed based on the new VDI pool settings.

HTTP Request

PUT $serverUrl/api/vdi-pools/:id

URL Parameters

Parameter Description
id The ID of the VDI pool

JSON Parameters

Same as Create.

Upload Logo for a VDI Pool

curl -XPUT "$serverUrl/api/vdi-pools/:id" \
  -H "Authorization: Bearer $accessToken" \
  -F 'vdiPool.logo=@filename'

The above command returns JSON structured like this:

{
  "success": true
}

This uses Content-Type: multipart/form-data to upload a custom logo file. The vdiPool.logo parameter can be a multipart file for both the create (POST) and update (PUT) endpoints.

HTTP Request

PUT $serverUrl/api/vdi-pools/:id

URL Parameters

Parameter Description
id The ID of the VDI pool

HTTP Headers

Header Description
Content-Type multipart/form-data is expected.

Parameters

Parameter Default Description
vdiPool.logo Image File png,jpg,svg

Delete a VDI Pool

curl -XDELETE "$serverUrl/api/vdi-pools/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint deletes an existing VDI pool.

HTTP Request

DELETE $serverUrl/api/vdi-pools/:id

URL Parameters

Parameter Description
id The ID of the VDI pool

List VDI Allocations

curl "$serverUrl/api/vdi-allocations" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "vdiAllocations": [
    {
      "id": 1,
      "pool": {
        "id": 3,
        "name": "My Desktop"
      },
      "instance": {
        "id": 397,
        "name": "my-desktop-12",
        "status": "provisioning"
      },
      "user": {
        "id": 53,
        "name": "Joseph D",
        "username": "jdoe"
      },
      "localUserCreated": false,
      "persistent": false,
      "recyclable": false,
      "status": "preparing",
      "dateCreated": "2021-04-22T18:38:38Z",
      "lastUpdated": "2021-04-22T18:38:39Z",
      "lastReserved": null,
      "releaseDate": "2021-04-22T20:38:39Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all VDI Allocations.

HTTP Request

GET $serverUrl/api/vdi-allocations

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort id Sort order
direction asc Sort direction, use 'desc’ to reverse sort
id Filter by allocation ID
status Filter by allocation status
poolId Filter by VDI Pool ID
userId Filter by User ID

Get a Specific VDI Allocation

curl "$serverUrl/api/vdi-allocations/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "vdiAllocation": {
    "id": 1,
    "pool": {
      "id": 3,
      "name": "My Desktop"
    },
    "instance": {
      "id": 397,
      "name": "my-desktop-12",
      "status": "provisioning"
    },
    "user": {
      "id": 53,
      "name": "Joseph D",
      "username": "jdoe"
    },
    "localUserCreated": false,
    "persistent": false,
    "recyclable": false,
    "status": "preparing",
    "dateCreated": "2021-04-22T18:38:38Z",
    "lastUpdated": "2021-04-22T18:38:39Z",
    "lastReserved": null,
    "releaseDate": "2021-04-22T20:38:39Z"
  }
}

This endpoint retrieves a specific VDI Allocation

HTTP Request

GET $serverUrl/api/vdi-allocations/:id

URL Parameters

Parameter Description
id ID of the VDI Allocation

List VDI Apps

curl "$serverUrl/api/vdi-apps" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "vdiApps": [
    {
      "id": 1,
      "name": "Notepad",
      "description": "A fine text editor",
      "launchPrefix": "||notepad",
      "logo": "$serverUrl/storage/uploads/uploads/VdiApp/1/logo/Notepad_Logo_original_original.png",
      "dateCreated": "2021-03-30T02:59:23Z",
      "lastUpdated": "2021-03-30T02:59:23Z"
    },
    {
      "id": 2,
      "name": "Explorer",
      "description": "A file browser",
      "launchPrefix": "!!explorer",
      "logo": "",
      "dateCreated": "2021-04-08T11:28:14Z",
      "lastUpdated": "2021-04-08T11:28:14Z"
    },
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all VDI Apps.

HTTP Request

GET $serverUrl/api/vdi-apps

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%
description Filter by description, wildcard may be specified as %. eg. example-%

Get a Specific VDI App

curl "$serverUrl/api/vdi-apps/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "vdiApp": {
    "id": 1,
    "name": "Notepad",
    "description": "A fine text editor",
    "launchPrefix": "||notepad",
    "logo": "$serverUrl/storage/uploads/uploads/VdiApp/1/logo/Notepad_Logo_original_original.png",
    "dateCreated": "2021-03-30T02:59:23Z",
    "lastUpdated": "2021-03-30T02:59:23Z"
  }
}

This endpoint retrieves a specific VDI App.

HTTP Request

GET $serverUrl/api/vdi-apps/:id

URL Parameters

Parameter Description
id ID of the VDI App

Create a VDI App

curl -XPOST "$serverUrl/api/vdi-apps" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "vdiApp": {
    "name": "Notepad",
    "description": "A fine text editor",
    "launchPrefix": "||notepad"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "vdiApp": {
    "id": 1,
    "name": "Notepad",
    "description": "A fine text editor",
    "launchPrefix": "||notepad",
    "logo": "",
    "dateCreated": "2021-03-30T02:59:23Z",
    "lastUpdated": "2021-03-30T02:59:23Z"
  }
}

This endpoint creates a new VDI App.

HTTP Request

POST $serverUrl/api/vdi-apps

JSON Parameters

Parameter Required Default Description
name Y Name
description N Description
iconPath N Icon Path. A relative location of an icon image, eg. /assets/containers-png/windows.png.
logo N Logo File, upload a custom logo, requires Content-Type: multipart/form-data
launchPrefix N Launch Prefix. The RDS App Name Prefix. Note: Must start with **

Update a VDI App

curl -XPUT "$serverUrl/api/vdi-apps/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "vdiApp": {
    "description": "A handy app"
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint updates an existing VDI App.

HTTP Request

PUT $serverUrl/api/vdi-apps/:id

URL Parameters

Parameter Description
id The ID of the VDI app

JSON Parameters

Same as Create.

Upload Logo for a VDI App

curl -XPUT "$serverUrl/api/vdi-apps/:id" \
  -H "Authorization: Bearer $accessToken" \
  -F 'vdiApp.logo=@filename'

The above command returns JSON structured like this:

{
  "success": true
}

This uses Content-Type: multipart/form-data to upload a custom logo file. The vdiApp.logo parameter can be a multipart file for both the create (POST) and update (PUT) endpoints.

HTTP Request

PUT $serverUrl/api/vdi-apps/:id

URL Parameters

Parameter Description
id The ID of the VDI app

HTTP Headers

Header Description
Content-Type multipart/form-data is expected.

Parameters

Parameter Default Description
vdiApp.logo Image File png,jpg,svg

Delete a VDI App

curl -XDELETE "$serverUrl/api/vdi-apps/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint deletes an existing VDI app.

HTTP Request

DELETE $serverUrl/api/vdi-apps/:id

URL Parameters

Parameter Description
id The ID of the VDI app

List VDI Gateways

curl "$serverUrl/api/vdi-gateways" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "vdiGateways": [
    {
      "id": 1,
      "name": "Gateway Example",
      "description": "An example of a VDI Gateway",
      "gatewayUrl": "https://vdigateway.mydomain",
      "apiKey": "40160686-d534-4566-9006-10fcb4797fa7",
      "dateCreated": "2021-04-08T10:45:20Z",
      "lastUpdated": "2021-04-08T10:45:20Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all VDI Gateways.

HTTP Request

GET $serverUrl/api/vdi-gateways

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%
description Filter by description, wildcard may be specified as %. eg. example-%

Get a Specific VDI Gateway

curl "$serverUrl/api/vdi-gateways/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "vdiGateway": {
    "id": 1,
    "name": "Gateway Example",
    "description": "An example of a VDI Gateway",
    "gatewayUrl": "https://vdigateway.mydomain",
    "apiKey": "40160686-d534-4566-9006-10fcb4797fa7",
    "dateCreated": "2021-04-08T10:45:20Z",
    "lastUpdated": "2021-04-08T10:45:20Z"
  }
}

This endpoint retrieves a specific VDI Gateway.

HTTP Request

GET $serverUrl/api/vdi-gateways/:id

URL Parameters

Parameter Description
id ID of the VDI Gateway

Create a VDI Gateway

curl -XPOST "$serverUrl/api/vdi-gateways" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "vdiGateway": {
    "name": "Gateway Example",
    "description": "An example of a VDI Gateway",
    "gatewayUrl": "https://vdigateway.mydomain"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "vdiGateway": {
    "id": 1,
    "name": "Gateway Example",
    "description": "An example of a VDI Gateway",
    "gatewayUrl": "https://vdigateway.mydomain",
    "dateCreated": "2021-04-08T10:45:20Z",
    "lastUpdated": "2021-04-08T10:45:20Z"
  }
}

This endpoint creates a new VDI Gateway.

HTTP Request

POST $serverUrl/api/vdi-gateways

JSON Parameters

Parameter Required Default Description
name Y Name
description N Description
gatewayUrl Y Gateway URL

Update a VDI Gateway

curl -XPUT "$serverUrl/api/vdi-gateways/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "vdiGateway": {
    "description": "The best VDI gateway to use"
  }
}'

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint updates an existing VDI Gateway.

HTTP Request

PUT $serverUrl/api/vdi-gateways/:id

URL Parameters

Parameter Description
id The ID of the VDI gateway

JSON Parameters

Same as Create.

Delete a VDI Gateway

curl -XDELETE "$serverUrl/api/vdi-gateways/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint deletes an existing VDI gateway.

HTTP Request

DELETE $serverUrl/api/vdi-gateways/:id

URL Parameters

Parameter Description
id The ID of the VDI gateway

Personas

The API provides endpoints for the Service Catalog persona as well.

Service Catalog

Provides API endpoints for the Service Catalog persona. This includes viewing the available types, viewing items in the inventory, and placing orders for new items to added to the inventory.

List Catalog Types

curl "$serverUrl/api/catalog/types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "catalogItemTypes": [
    {
      "id": 1,
      "name": "apache",
      "description": "Example apache instance",
      "type": "instance",
      "featured": true,
      "imagePath": "/assets/containers-png/apache.png"
    },
    {
      "id": 2,
      "name": "example",
      "description": "Example catalog item",
      "type": "instance",
      "featured": true,
      "imagePath": "/assets/containers-png/apache.png"
    },
    {
      "id": 3,
      "name": "example",
      "description": null,
      "type": "workflow",
      "context": "instance",
      "featured": false,
      "imagePath": "/assets/containers-png/morph-resource2.png"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 3,
    "total": 3
  }
}

This endpoint retrieves the types available for ordering.

HTTP Request

GET $serverUrl/api/catalog/types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%
description Filter by description, wildcard may be specified as %. eg. example-%
featured Filter by featured, eg. true or false

Get a Specific Catalog Type

curl "$serverUrl/api/catalog/types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "catalogItemType": {
    "id": 1,
    "name": "example",
    "description": "Example catalog item",
    "type": "blueprint",
    "featured": true,
    "imagePath": "/assets/containers-png/morph-resource2.png",
    "optionTypes": [
      {
        "id": 1717,
        "name": "App Name",
        "description": "Name of your app",
        "code": null,
        "fieldName": "appName",
        "fieldLabel": "App Name",
        "fieldCode": null,
        "fieldContext": "config.customOptions",
        "fieldGroup": null,
        "fieldClass": null,
        "fieldAddOn": null,
        "fieldComponent": null,
        "fieldInput": null,
        "placeHolder": null,
        "verifyPattern": null,
        "helpBlock": null,
        "defaultValue": null,
        "optionSource": null,
        "optionList": null,
        "type": "text",
        "advanced": false,
        "required": true,
        "exportMeta": false,
        "editable": false,
        "creatable": true,
        "config": {
        },
        "displayOrder": 0,
        "wrapperClass": null,
        "enabled": true,
        "noBlank": false,
        "dependsOnCode": null,
        "visibleOnCode": null,
        "contextualDefault": false,
        "displayValueOnDetails": false
      }
    ]
  }
}

This endpoint retrieves a specific catalog item type. This also returns an array of associated optionTypes that are used to configure the catalog item.

HTTP Request

GET $serverUrl/api/catalog/types/:id

URL Parameters

Parameter Description
id ID of the Catalog Item Type

List Catalog Inventory Items

curl "$serverUrl/api/catalog/items" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "items": [
    {
      "id": 1,
      "name": "apache-1",
      "type": {
        "id": 1,
        "name": "apache",
        "type": "instance"
      },
      "quantity": 1,
      "status": "ORDERED",
      "statusMessage": null,
      "refType": "Instance",
      "instance": {
        "id": 403,
        "name": "apache-1",
        "status": "running",
        "locations": [
          "Http: 10.200.12.44:80"
        ],
        "virtualMachines": 1,
        "version": "2.4"
      },
      "orderDate": "2020-11-06T01:47:05Z",
      "dateCreated": "2020-11-06T01:47:00Z",
      "lastUpdated": "2020-11-06T01:47:06Z"
    },
    {
      "id": 2,
      "name": "example-1",
      "type": {
        "id": 2,
        "name": "example",
        "type": "blueprint"
      },
      "quantity": 1,
      "status": "ORDERED",
      "statusMessage": null,
      "refType": "App",
      "app": {
        "id": 88,
        "name": "example-1",
        "status": "running",
        "instances": [
          {
            "id": 402,
            "name": "example-1",
            "status": "running",
            "locations": [
              "Http: 54.183.8.230:80"
            ],
            "virtualMachines": 1,
            "version": "1.9"
          }
        ]
      },
      "orderDate": "2020-11-06T01:46:42Z",
      "dateCreated": "2020-11-06T01:46:42Z",
      "lastUpdated": "2020-11-06T01:46:44Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves a list of the catalog inventory items.

HTTP Request

GET $serverUrl/api/catalog/items

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%

Get a Specific Catalog Inventory Item

curl "$serverUrl/api/catalog/items/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "item": {
    "id": 1,
    "name": "apache-1",
    "type": {
      "id": 27,
      "name": "apache",
      "type": "instance"
    },
    "quantity": 1,
    "status": "ORDERED",
    "statusMessage": null,
    "refType": "Instance",
    "instance": {
      "id": 403,
      "name": "apache-1",
      "status": "running",
      "locations": [
        "Http: 10.200.12.44:80"
      ],
      "virtualMachines": 1,
      "version": "2.4"
    },
    "orderDate": "2020-11-06T01:47:05Z",
    "dateCreated": "2020-11-06T01:47:00Z",
    "lastUpdated": "2020-11-06T01:47:06Z"
  }
}

This endpoint retrieves a specific catalog inventory item.

HTTP Request

GET $serverUrl/api/catalog/items/:id

URL Parameters

Parameter Description
id ID of the Catalog Item

Get Catalog Cart

curl "$serverUrl/api/catalog/cart" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "cart": {
    "id": 1,
    "name": null,
    "items": [
      {
        "id": 27,
        "type": {
          "id": 2,
          "name": "apache",
          "type": "instance"
        },
        "quantity": 1,
        "price": 6.2508,
        "currency": "USD",
        "unit": "month",
        "valid": true,
        "status": "IN_CART",
        "dateCreated": "2020-11-06T20:33:39Z",
        "lastUpdated": "2020-11-06T20:33:39Z"
      }
    ],
    "stats": {
      "price": 6.2508,
      "currency": "USD",
      "unit": "month"
    }
  }
}

This endpoint retrieves the current catalog cart and all the items in it.

HTTP Request

GET $serverUrl/api/catalog/cart

Add Catalog Item to Cart

curl -XPOST "$serverUrl/api/catalog/cart/items" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "type": {
      "name": "example"
    },
    "config": {
      "appName": "My App"
    },
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "item": {
    "id": 34,
    "type": {
      "id": 2,
      "name": "example",
      "type": "blueprint"
    },
    "quantity": 1,
    "price": 6.2508,
    "currency": "USD",
    "unit": "month",
    "valid": true,
    "status": "IN_CART",
    "dateCreated": "2020-11-06T20:14:29Z",
    "lastUpdated": "2020-11-06T20:14:29Z"
  }
}

Use this command to add an item to your service catalog cart.

HTTP Request

POST $serverUrl/api/catalog/cart/items

Query Parameters

Parameter Default Description
validate false Validate Only. Use true to validate the configuration without actually adding the item to the cart.

JSON Parameters

Parameter Required Description
config Y Config Object, required options depend on the catalog item type’s associated option types. The values passed in here are injected into the instance config or app spec or workflow script(s) defined by the type.
context N Context Type for running the workflow, determines if a target resource must be selected. instance,server, or appliance. This may only be passed if the type allows it, usually the type determines the context for the user. Only applies to type workflow.
target N Resource (Instance or Server) ID for context when running the workflow. Only applies to type workflow and only required when context is instance or server.

Remove a Catalog Item From Cart

curl -XDELETE "$serverUrl/api/catalog/cart/items/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will remove a catalog item that is currently in the cart.

HTTP Request

DELETE $serverUrl/api/catalog/cart/items/:id

URL Parameters

Parameter Description
id The ID of the catalog item

Clear Catalog Cart

curl -XDELETE "$serverUrl/api/catalog/cart" \
  -H "Authorization: Bearer $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Use this command to empty your cart, deleting all the items in it.

HTTP Request

DELETE $serverUrl/api/catalog/cart

Checkout Catalog Cart

curl -XPOST "$serverUrl/api/catalog/checkout" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "msg": "Order created"
}

Use this command to checkout, finalizing your cart and placing an order. This converts each item in the cart to an inventory item, changing the status from IN_CART to ORDERED and potentially starts the provisioning process for each item.

HTTP Request

POST $serverUrl/api/catalog/checkout

Place Catalog Order

curl -XPOST "$serverUrl/api/catalog/orders" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {
    "items": [
      {
        "type": {
          "name": "example"
        },
        "config": {
          "appName": "woot"
        }
      }
    ]
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "item": {
    "id": 34,
    "type": {
      "id": 2,
      "name": "example",
      "type": "blueprint"
    },
    "quantity": 1,
    "price": 6.2508,
    "currency": "USD",
    "unit": "month",
    "valid": true,
    "status": "IN_CART",
    "dateCreated": "2020-11-06T20:14:29Z",
    "lastUpdated": "2020-11-06T20:14:29Z"
  }
}

This will place an order for the specified items, adding items to the inventory right away, without using the cart.

HTTP Request

POST $serverUrl/api/catalog/orders

Query Parameters

Parameter Default Description
validate false Validate Only. Use true to validate the configuration without actually placing the order or adding items to your inventory

JSON Parameters

Parameter Required Description
name N Order Name as a way to identify the order.
items N Array of Item objects, each item in the order can be configured individually, see Add Catalog Item to Cart.

Delete a Catalog Inventory Item

curl -XDELETE "$serverUrl/api/catalog/items/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a catalog inventory item, which by default will deprovision any associated any instances and servers.

HTTP Request

DELETE $serverUrl/api/catalog/items/:id

URL Parameters

Parameter Description
id The ID of the catalog item

Query Parameters

Parameter Default Description
preserveVolumes off Preserve Volumes
keepBackups off Preserve copy of backups
releaseEIPs on Release EIPs
removeInstances on Remove Instances. Only applies to type blueprint (Apps)
force off Force Delete

Virtual Desktop

Provides API endpoints for the Virtual Desktop persona. This includes viewing the available virtual desktops (VDI pools) and allocating them for your own personal use.

List Virtual Desktops

curl "$serverUrl/api/vdi" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "desktops": [
    {
      "id": 1,
      "logo": "/assets/containers-png/morph-resource2.png",
      "name": "Windows Desktop",
      "description": "A fancy windows desktop",
      "status": "available",
      "allocationStatus": "preparing",
      "allocation": null
    },
    {
      "id": 2,
      "logo": "/assets/containers-png/windows.png",
      "name": "Test Desktop",
      "description": "",
      "status": "available",
      "allocationStatus": "preparing",
      "apps": [
        {
          "id": 1,
          "logo": "$serverUrl/storage/uploads/uploads/VdiApp/1/logo/Notepad_Logo_original_original.png",
          "name": "Notepad",
          "launchPrefix": "||notepad"
        }
      ],
      "allocation": null
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all virtual desktops (VDI pools) along with the allocation for your user if one exists.

HTTP Request

GET $serverUrl/api/vdi

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by wildcard search of name and description
name Filter by name, wildcard may be specified as %, eg. example-%
description Filter by description, wildcard may be specified as %. eg. example-%

Get a Specific Virtual Desktop

curl "$serverUrl/api/vdi/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "desktop": {
    "id": 1,
    "logo": "/assets/containers-png/morph-resource2.png",
    "name": "Windows Desktop",
    "description": "A fancy windows desktop",
    "status": "available",
    "allocationStatus": "preparing",
    "allocation": {
      "id": 11,
      "poolId": 1,
      "pool": {
        "id": 1,
        "name": "Test"
      },
      "instance": {
        "id": 433,
        "name": "vdi-test-3",
        "status": "provisioning"
      },
      "user": {
        "id": 3,
        "name": "Thomas A",
        "username": "tanderson"
      },
      "localUserCreated": false,
      "persistent": false,
      "status": "preparing",
      "dateCreated": "2021-04-13T12:48:15Z",
      "lastUpdated": "2021-04-13T12:48:15Z",
      "lastReserved": null,
      "releaseDate": "2021-04-13T18:48:15Z"
    }
  }
}

This endpoint retrieves a specific virtual desktop (VDI pool) along with the allocation for your user if one exists.

HTTP Request

GET $serverUrl/api/vdi/:id

URL Parameters

Parameter Description
id ID of the Virtual Desktop (VDI Pool)

Allocate Virtual Desktop

curl -XPOST "$serverUrl/api/vdi/1/allocate" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON Structured like this:

{
  "success": true,
  "desktop": {
    "id": 1,
    "logo": "/assets/containers-png/windows.png",
    "name": "Test",
    "status": "available",
    "allocationStatus": "preparing",
    "allocation": {
      "id": 11,
      "poolId": 1,
      "pool": {
        "id": 1,
        "name": "Test"
      },
      "instance": {
        "id": 433,
        "name": "vdi-test-3",
        "status": "provisioning"
      },
      "user": {
        "id": 3,
        "name": "Thomas A",
        "username": "tanderson"
      },
      "localUserCreated": false,
      "persistent": false,
      "status": "preparing",
      "dateCreated": "2021-04-13T12:48:15Z",
      "lastUpdated": "2021-04-13T12:48:15Z",
      "lastReserved": null,
      "releaseDate": "2021-04-13T18:48:15Z"
    }
  }
}

This endpoint allocates a specific virtual desktop (VDI pool) for use by your user. It will return the desktop and its allocation for your user, or an error if allocation fails, which will occur if the desktop is fully allocated already. If your user already has an allocation, the desktop and allocation will still be returned succesfully and the server does not make any changes.

HTTP Request

POST $serverUrl/api/vdi/:id/allocate

URL Parameters

Parameter Description
id ID of the Virtual Desktop (VDI Pool)

Administration

The Admin endpoints are for appliance administration. This includes management of Users, Tenants, Roles and the various appliance settings.

Tenants

Provides API interfaces for managing the creation and modification of tenants within Morpheus. Typically this is only accessible by users of the Master Tenant.

A Tenant may also be referred to as an Account or account.

Get All Tenants

curl "$serverUrl/api/accounts" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "accounts": [
    {
      "id": 1,
      "name": "Master",
      "description": "The master tenant",
      "subdomain": null,
      "currency": "USD",
      "externalId": null,
      "customerNumber": null,
      "accountNumber": null,
      "accountName": null,
      "active": true,
      "master": true,
      "role": {
        "id": 1,
        "authority": "System Admin",
        "description": "Super User"
      },
      "stats": {
        "instanceCount": 42,
        "userCount": 13
      },
      "lastUpdated": "2015-11-10T18:58:55Z",
      "dateCreated": "2015-11-10T18:58:55Z",
    },
    {
      "id": 2,
      "name": "Acme",
      "description": "The Acme corporation, a global manufacturer of outlandish products",
      "subdomain": "acme",
      "currency": "USD",
      "externalId": null,
      "customerNumber": "1920",
      "accountNumber": "AC1920",
      "accountName": "Acme Corporation",
      "active": true,
      "master": false,
      "role": {
        "id": 2,
        "authority": "Tenant Admin",
        "description": "Tenant Role Template"
      },
      "stats": {
        "instanceCount": 2,
        "userCount": 1
      },
      "dateCreated": "2020-11-18T17:40:40Z",
      "lastUpdated": "2020-11-18T17:40:40Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint retrieves all tenants.

HTTP Request

GET $serverUrl/api/accounts

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by matching name or description
name Filter by name
lastUpdated Date filter, restricts query to only load tenants updated more recently than the date specified

Get a Specific Tenant

curl "$serverUrl/api/accounts/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "account": {
    "id": 2,
    "name": "Acme",
    "description": "The Acme corporation, global manufacturer of outlandish products",
    "subdomain": "acme",
    "currency": "USD",
    "externalId": null,
    "customerNumber": "1920",
    "accountNumber": "AC1920",
    "accountName": "Acme Corporation",
    "active": true,
    "master": false,
    "role": {
      "id": 2,
      "authority": "Tenant Admin",
      "description": "Tenant Role Template"
    },
    "stats": {
      "instanceCount": 2,
      "userCount": 1
    },
    "dateCreated": "2020-11-18T17:40:40Z",
    "lastUpdated": "2020-11-18T17:40:40Z"
  }
}

This endpoint will retrieve a specific account by ID.

HTTP Request

GET $serverUrl/api/accounts/:id

Create a Tenant

curl -XPOST "$serverUrl/api/accounts" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"account":{
    "name": "Acme",
    "description": "The Acme corporation, global manufacturer of outlandish products",
    "subdomain": "acme",
    "role": {
      "id": 2
    },
    "active": true,
    "currency": "USD",
    "customerNumber": "1920",
    "accountNumber": "AC1920",
    "accountName": "Acme Corporation"
  }}'

The above command returns JSON structured like getting a single account:

HTTP Request

POST $serverUrl/api/accounts

JSON Account Parameters

Parameter Default Description
name A unique name for the account
description Optional description field if you want to put more info there
subdomain Sets the custom login url or login prefix for logging into a sub-tenant user.
role Tenant Admin A nested id of the default base role for the account. See Get Available Roles for a Tenant.
active true Set to false to deactvate the account
currency USD Currency ISO Code to be used for the account
customerNumber Customer Number, an optional field that can be used for billing and accounting.
accountNumber Account Number, an optional field that can be used for billing and accounting.
accountName Account Name, an optional field that can be used for billing and accounting.

Updating a Tenant

curl -XPUT "$serverUrl/api/accounts/3" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"account":{
    "name": "Batman",
    "description": "Crime fighter",
    "subdomain": "batman",
    "role": {
      "id": 2
    },
    "active": true,
    "currency": "USD",
    "customerNumber": "1020",
    "accountNumber": "A1020-GPD",
    "accountName": "Gotham Police Department"
  }}'

The above command returns JSON structured like getting a single account:

HTTP Request

PUT $serverUrl/api/accounts/:id

JSON Account Parameters

Parameter Default Description
name A unique name for the account
description Optional description field if you want to put more info there
subdomain Sets the custom login url or login prefix for logging into a sub-tenant user.
role A nested id of the default base role for the account
active Set to false to deactvate the account
currency Currency ISO Code to be used for the account
customerNumber Customer Number, an optional field that can be used for billing and accounting.
accountNumber Account Number, an optional field that can be used for billing and accounting.
accountName Account Name, an optional field that can be used for billing and accounting.

Delete a Tenant

curl -XDELETE "$serverUrl/api/accounts/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

If a tenant still has instances tied to it, the delete will fail unless removeResources=on is passed.

HTTP Request

DELETE $serverUrl/api/accounts/:id

Query Parameters

Parameter Default Description
removeResources on Remove Infrastructure.

Get Available Roles for a Tenant

curl "$serverUrl/api/accounts/available-roles" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "roles": [
     {
      "id": 1,
      "authority": "System Admin",
      "name": "System Admin",
      "description": "Super User",
      "roleType": null,
      "owner": null
    },
    {
      "id": 2,
      "authority": "Tenant Admin",
      "name": "Tenant Admin",
      "description": "Tenant Role Template",
      "roleType": "account",
      "owner": null
    }
  ]
}

This endpoint will retrieve a list of roles that can be assigned as the base role for a tenant account. These are roles that have roleType set to account or null.

HTTP Request

GET $serverUrl/api/accounts/available-roles

Subtenant Groups

Groups belonging to a subtenant can be managed by the master account.

curl "$serverUrl/api/accounts/20/groups" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "groups": [
    {
      "id": 365,
      "name": "testgroup",
      "code": "testgroup",
      "location": "West",
      "accountId": 20,
      "visibility": "public",
      "active": true,
      "dateCreated": "2018-03-20T20:34:22+0000",
      "lastUpdated": "2018-03-31T18:32:56+0000",
      "zones": [
        {
          "id": 32,
          "name": "test-google"
        },
        {
          "id": 33,
          "name": "test-vmware"
        }
      ]
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  }
}

This endpoint retrieves all groups and a list of zones associated with the group by id.

HTTP Request

GET $serverUrl/api/accounts/:accountId/groups

URL Parameters

Parameter Description
accountId The ID of the subtenant account

Query Parameters

Parameter Default Description
phrase Filter on partial match of name or location
name Filter on exact match of name
lastUpdated A date filter, restricts query to only load groups updated more recent or equal to the date specified

Get a Specific Group for Subtenant

curl "$serverUrl/api/accounts/20/groups/365" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "group": {
      "id": 365,
      "name": "testgroup",
      "code": "testgroup",
      "location": "West",
      "accountId": 20,
      "visibility": "public",
      "active": true,
      "dateCreated": "2018-03-20T20:34:22+0000",
      "lastUpdated": "2018-03-31T18:32:56+0000",
      "zones": [
        {
          "id": 32,
          "name": "test-google"
        },
        {
          "id": 33,
          "name": "test-vmware"
        }
      ]
    }
}

This endpoint retrieves a specific group.

HTTP Request

GET $serverUrl/api/accounts/:accountId/groups/:id

URL Parameters

Parameter Description
accountId The ID of the subtenant account
id The ID of the group to retrieve

Create a Group for Subtenant

curl -XPOST "$serverUrl/api/accounts/20/groups" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"group":{
    "name": "My Group",
    "description": "My description",
    "location": "West"
  }}'

The above command returns JSON structured like getting a single group:

HTTP Request

POST $serverUrl/api/accounts/:accountId/groups

URL Parameters

Parameter Description
accountId The ID of the subtenant account

JSON Parameters

Parameter Default Description
name A unique name scoped to the subtenant for the group
description Optional description field if you want to put more info there
code Optional code for use with policies
location Optional location argument for the group

Updating a Group for Subtenant

curl -XPUT "$serverUrl/api/accounts/20/groups/365" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"group":{
    "name": "My Group",
    "description": "My description",
    "location": "West"
  }}'

The above command returns JSON structured like getting a single group:

HTTP Request

PUT $serverUrl/api/accounts/:accountId/groups/:id

URL Parameters

Parameter Description
accountId The ID of the subtenant account
id The ID of the group

JSON Parameters

Parameter Default Description
name A unique name scoped to the subtenant for the group
description Optional description field if you want to put more info there
code Optional code for use with policies
location Optional location for the group

Updating Group Zones for Subtenant

curl -XPUT "$serverUrl/api/accounts/20/groups/365/update-zones" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"group":{
    "zones": [
      {"id": 32}, {"id": 33}, {"id": 34}
    ]
  }}'

The above command returns JSON Structured like this:

{
  "success": true
}

This will update the zones that are assigned to the group. Any zones that are not passed in the zones parameter will be removed from the group.

HTTP Request

PUT $serverUrl/api/accounts/:id/groups/:groupId/update-zones

JSON Parameters

Parameter Default Description
zones An array of all the zones assigned to this group.

Delete a Group for Subtenant

curl -XDELETE "$serverUrl/api/accounts/20/groups/365" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/accounts/:id/groups/:groupId

If a group has zones or servers still tied to it, a delete action will fail

Roles

Provides API interfaces for managing the creation and modification of roles within Morpheus. This API is scoped to the roles owned by the current user’s account. System Admin users will also be able to access the system roles: System Admin and Account Admin.

Get All Roles

curl "$serverUrl/api/roles"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "roles": [
        {
      "id": 2,
      "authority": "Account Admin",
      "description": "Service account holder",
      "dateCreated": "2016-08-27T23:26:19+0000",
      "lastUpdated": "2016-08-27T23:26:19+0000",
      "scope": "Account",
      "ownerId": null,
      "owner": null,
      "defaultPersona": null
    },
    {
      "id": 1,
      "authority": "System Admin",
      "description": "Super User",
      "dateCreated": "2015-11-10T18:58:55+0000",
      "lastUpdated": "2015-11-10T18:58:55+0000",
      "scope": "Admin",
      "ownerId": null,
      "owner": null,
      "defaultPersona": null
    },
    {
      "id": 3,
      "authority": "Another Role",
      "description": "A custom role",
      "dateCreated": "2015-11-10T19:01:45+0000",
      "lastUpdated": "2015-11-10T19:02:01+0000",
      "scope": "Account",
      "ownerId": 1,
      "owner": {
        "id": 1,
        "name": "Root Account"
      },
      "defaultPersona": null
    },
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 3,
    "total": 3
  }
}

This endpoint retrieves all roles.

HTTP Request

GET $serverUrl/api/roles

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Filter by matching authority
authority Filter by authority

Get a Specific Role

curl "$serverUrl/api/roles/3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "role": {
    "id": 3,
    "authority": "Another Role",
    "description": "A custom role",
    "dateCreated": "2015-11-10T19:01:45+0000",
    "lastUpdated": "2015-11-10T19:02:01+0000",
    "scope": "Account",
    "ownerId": 1,
    "owner": {
      "id": 1,
      "name": "Root Account"
    },
    "defaultPersona": null
  },
  "featurePermissions": [
    {
      "id": 8,
      "code": "admin-users",
      "name": "Admin: Users",
      "access": "full"
    },
    {
      "id": 18,
      "code": "backups",
      "name": "Backups",
      "access": "full"
    },
    {
      "id": 19,
      "code": "dashboard",
      "name": "Dashboard",
      "access": "read"
    },
  ],
  "globalSiteAccess": "custom",
  "sites": [
    {
      "id": 1,
      "name": "group1",
      "access": "full"
    },
    {
      "id": 2,
      "name": "group2",
      "access": "none"
    }
  ],
  "globalZoneAccess": "full",
  "zones": [
    {
      "id": 1,
      "name": "zone1",
      "access": "full"
    },
    {
      "id": 2,
      "name": "zone2",
      "access": "full"
    },
  ],
  "globalInstanceTypeAccess": "custom",
  "instanceTypePermissions": [
    {
      "id": 1,
      "code": "activemq",
      "name": "ActiveMQ",
      "access": "full"
    },
    {
      "id": 2,
      "code": "amazon",
      "name": "Amazon",
      "access": "full"
    },
    {
      "id": 5,
      "code": "ansible",
      "name": "Ansible",
      "access": "full"
    },
  ],
  "globalAppTemplateAccess": "full",
  "appTemplatePermissions": [],
  "globalCatalogItemTypeAccess": "full",
  "catalogItemTypePermissions": [
    {
      "id": 1,
      "code": "app1",
      "name": "App 1",
      "access": "full"
    },
    {
      "id": 2,
      "code": "app2",
      "name": "App 2",
      "access": "full"
    }
  ],
  "personaPermissions": [
    {
      "id": 1,
      "code": "standard",
      "name": "Standard",
      "access": "full"
    },
    {
      "id": 2,
      "code": "serviceCatalog",
      "name": "Service Catalog",
      "access": "full"
    }
  ],
  "globalVdiPoolAccess": "custom",
  "vdiPoolPermissions": [
    {
      "id": 1,
      "name": "Desktop 1",
      "access": "full"
    },
    {
      "id": 2,
      "name": "Desktop 2",
      "access": "none"
    }
  ],
  "globalReportTypeAccess": "custom",
  "reportTypePermissions": [
    {
      "id": 21,
      "code": "appCost",
      "name": "Application Cost",
      "access": "full"
    },
    {
      "id": 5,
      "code": "cloudCost",
      "name": "cloud Cost",
      "access": "none"
    }
  ],
}

The sample JSON above shows only a small subset of the featurePermissions, instanceTypePermissions and reportTypePermissions that exist.

This endpoint will retrieve a specific role by id if the user has permission to access the role.

HTTP Request

GET $serverUrl/api/roles/:id

Create a Role

curl -XPOST "$serverUrl/api/roles" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"role":{
    "authority": "Test Role",
    "description": "A test role",
    "baseRoleId": 2,
    "roleType": "user"
  }}'

The above command returns JSON structured like getting a single role:

HTTP Request

POST $serverUrl/api/roles

JSON Role Parameters

Parameter Default Description
authority A name for the role
description Optional description field if you want to put more info there
baseRoleId A role to copy feature permissions and access from (optional)
roleType The type of role to be created. Accepted values are either ‘user’ to create a User role or 'account’ to create a Tenant role
multitenant false A Multitenant role is automatically copied into all existing subtenants as well as placed into a subtenant when created. Useful for providing a set of predefined roles a Customer can use
multitenantLocked false Prevents subtenants from branching off this role/modifying it
defaultPersona.code Default Persona code, eg. standard or serviceCatalog

Updating Basic Role Settings

curl -XPUT "$serverUrl/api/roles/4" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"role":{
    "authority": "Test Role",
    "description": "A new description of test role",
    "defaultPersona": {"code": "serviceCatalog"}
  }}'

The above command returns JSON structured like getting a single role:

HTTP Request

PUT $serverUrl/api/roles/:id

JSON Role Parameters

Parameter Default Description
authority A name for the role
description Optional description field if you want to put more info there
multitenant false A Multitenant role is automatically copied into all existing subtenants as well as placed into a subtenant when created. Useful for providing a set of predefined roles a Customer can use
multitenantLocked false Prevents subtenants from branching off this role/modifying it
defaultPersona.code Default Persona code, eg. standard or serviceCatalog

Updating Role Feature Permissions

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "admin-users",
    "access": "read"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "read"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode The code of the permission being changed
access The new access level. full, read, none

Global Group Access

Global Group Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "ComputeSite",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode ComputeSite is the code for Global Group Access
access full, custom, read, or none

Customizing Group Access

Global Group Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-group" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": 2,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-group

JSON Parameters

Parameter Default Description
groupId id of the group (site)
access full, read, or none

Global Cloud Access

Global Cloud Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "ComputeZone",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode ComputeZone is the code for Global Cloud Access
access full, custom, or none

Customizing Cloud Access

Global Cloud Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-cloud" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "cloudId": 2,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-cloud

JSON Parameters

Parameter Default Description
cloudId id of the cloud (zone)
access full, read, or none

Global Instance Type Access

Global Instance Type Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "InstanceType",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode InstanceType is the code for Global Instance Type Access
access full, custom, or none

Customizing Instance Type Access

Global Instance Type Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-instance-type" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceTypeId": 1,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-instance-type

JSON Parameters

Parameter Default Description
instanceTypeId id of the instance type
access full or none

Global Blueprint Access

Global Blueprint Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "AppTemplate",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode AppTemplate is the code for Global Blueprint Access
access full, custom, or none

Customizing Blueprint Access

Global Blueprint Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-blueprint" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "appTemplateId": 2,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-blueprint

JSON Parameters

Parameter Default Description
appTemplateId id of the blueprint (appTemplate)
access full, read, or none

HTTP Request

PUT $serverUrl/api/roles/:id/update-cloud

JSON Parameters

Parameter Default Description
cloudId id of the cloud (zone)
access full, read, or none

Global Catalog Item Type Access

Global Catalog Item Type Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "CatalogItemType",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode CatalogItemType is the code for Global Catalog Item Type Access
access full, custom, or none

Customizing Catalog Item Type Access

Global Catalog Item Type Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-catalog-item-type" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogItemTypeId": 1,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-catalog-item-type

JSON Parameters

Parameter Default Description
catalogItemTypeId id of the catalog item type
access full or none

Customizing Persona Access

curl -XPUT "$serverUrl/api/roles/4/update-persona" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "personaCode": "serviceCatalog",
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-persona

JSON Parameters

Parameter Default Description
personaCode code of the Persona, eg. standard or serviceCatalog
access full or none

Global VDI Pool Access

Global VDI Pool Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "VdiPools",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode VdiPools is the code for Global VDI Pool Access
access full, custom, or none

Customizing VDI Pool Access

Global VDI Pool Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-vdi-pool" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "vdiPoolId": 1,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-vdi-pool

JSON Parameters

Parameter Default Description
vdiPoolId id of the VDI pool
access full or none

Global Report Type Access

Global Report Type Access is controlled via the update-permission API

curl -XPUT "$serverUrl/api/roles/4/update-permission" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCode": "ReportTypes",
    "access": "custom"
  }'

HTTP Request

PUT $serverUrl/api/roles/:id/update-permission

JSON Parameters

Parameter Default Description
permissionCode ReportTypes is the code for Global Report Type Access
access full, custom, or none

Customizing Report Type Access

Global Report Type Access must first be changed to custom as seen above.

curl -XPUT "$serverUrl/api/roles/4/update-report-type" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "reportTypeId": 1,
    "access": "full"
  }'

The above command returns JSON Structured like this:

{
  "success": true,
  "access": "full"
}

HTTP Request

PUT $serverUrl/api/roles/:id/update-report-type

JSON Parameters

Parameter Default Description
reportTypeId id of the report type
access full or none

Delete a Role

curl -XDELETE "$serverUrl/api/roles/4" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/roles/:id

If a role still has accounts or users tied to it, The delete will fail.

Users

Users are meant to represent people or services that will be using the Morpheus appliance. Users belong to a Tenant (Account).

Get All Users

curl "$serverUrl/api/users"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "users": [
    {
      "id": 1,
      "accountId": 1,
      "username": "admin",
      "displayName": "Morpheus Admin",
      "email": "admin@morpheusdata.com",
      "firstName": "Morpheus",
      "lastName": "Admin",
      "enabled": true,
      "receiveNotifications": true,
      "isUsing2FA": true,
      "accountExpired": false,
      "accountLocked": false,
      "passwordExpired": false,
      "loginCount": 42,
      "loginAttempts": 0,
      "lastLoginDate": "2021-04-17T00:12:01Z",
      "roles": [
        {
          "id": 1,
          "authority": "System Admin",
          "description": "Super User"
        }
      ],
      "account": {
        "id": 1,
        "name": "morpheusdata.com"
      },
      "linuxUsername": "morphadmin",
      "linuxPassword": null,
      "linuxKeyPairId": 5,
      "windowsUsername": "morphadmin",
      "windowsPassword": "************",
      "defaultPersona": {
        "id": 1,
        "code": "standard",
        "name": "Standard"
      },
      "dateCreated": "2016-08-27T19:28:09Z",
      "lastUpdated": "2021-04-17T00:12:01Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 1,
    "total": 1
  },
  "global" false
}

This endpoint retrieves all users in the current user’s tenant account. Master tenant users with permission to manage subtenants can use global=true to find users across all tenants.

HTTP Request

GET $serverUrl/api/users

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort order
phrase Filter by matching any part of firstName, lastName, username, or email
username Filter by username
firstName Filter by firstName
lastName Filter by lastName
email Filter by email
lastUpdated Date filter, restricts query to only load users updated timestamp is more recent or equal to the date specified
tenantId Filter by Tenant ID. This is only available to master tenant users with permission to manage tenants and users.
global false Global (All Tenants), load users from all tenants. The default is to only see your own tenant. This is only available to master tenant users with permission to manage tenants and users.

Get All Users Across All Tenants

curl "$serverUrl/api/users?global=true"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like Get All Users for a Tenant

Using global=true is a way to list users across all tenants. This is only available to master tenant users with permission to manage users and tenants.

HTTP Request

GET $serverUrl/api/users?global=true

Query Parameters

The same as Get All Users.

Get a Specific User

curl "$serverUrl/api/users/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "user": {
    "id": 1,
    "accountId": 1,
    "username": "admin",
    "displayName": "Morpheus Admin",
    "email": "admin@morpheusdata.com",
    "firstName": "Morpheus",
    "lastName": "Admin",
    "enabled": true,
    "receiveNotifications": true,
    "isUsing2FA": true,
    "accountExpired": false,
    "accountLocked": false,
    "passwordExpired": false,
    "loginCount": 42,
    "loginAttempts": 0,
    "lastLoginDate": "2021-04-17T00:12:01Z",
    "roles": [
      {
        "id": 1,
        "authority": "System Admin",
        "description": "Super User"
      }
    ],
    "account": {
      "id": 1,
      "name": "morpheusdata.com"
    },
    "linuxUsername": "morphadmin",
    "linuxPassword": null,
    "linuxKeyPairId": 5,
    "windowsUsername": "morphadmin",
    "windowsPassword": "************",
    "defaultPersona": {
      "id": 1,
      "code": "standard",
      "name": "Standard"
    },
    "dateCreated": "2016-08-27T19:28:09Z",
    "lastUpdated": "2021-04-17T00:12:01Z"
    "access": {
      "features": [
        {
          "id": 11,
          "code": "admin-appliance",
          "name": "Admin: Appliance Settings",
          "access": "full"
        }
      ],
      "zones": [
        {
          "id": 1,
          "name": "zone1",
          "access": "full"
        }
      ],
      "sites": [
        {
          "id": 1,
          "name": "AWS",
          "access": "full"
        }
      ],
      "instanceTypes": [
        {
          "id": 1,
          "code": "activemq",
          "name": "ActiveMQ",
          "access": "full"
        }
      ],
      "appTemplates": [
        {
          "id": 1,
          "name": "Blank Apache",
          "access": "full"
        }
      ]
    }
  }
}

This endpoint will retrieve a specific user by id if the user has permission to access the user.

HTTP Request

GET $serverUrl/api/users/:id

URL Parameters

Parameter Description
id The ID of the User

Query Parameters

Parameter Default Description
includeAccess Include access information in the response. This is the permissions, clouds, instanceTypes, etc. that the user is authorized for based on their assigned Role(s).

Create a User

curl -XPOST "$serverUrl/api/users" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"user":{
    "username": "testuser",
    "email": "testuser@morpheusdata.com",
    "firstName": "Test",
    "lastName": "User",
    "password": "aStr0ngp@ssword",
    "roles": [{"id": 1}]
  }}'

The above command returns JSON structured like getting a single user

HTTP Request

POST $serverUrl/api/users

JSON User Parameters

Parameter Default Description
username A unique username
email The user’s email
firstName The user’s first name (optional)
lastName The user’s last name (optional)
password The password to apply to the user
roles Array of objects with id of the role(s) to assign to the user. See Get Available Roles for a User.
receiveNotifications true Receive Notifications?
linuxUsername Linux Username, user settings for provisioning
linuxPassword Linux Password, user settings for provisioning
linuxKeyPairId Linux SSH Key, user settings for provisioning
windowsUsername Windows Username, user settings for provisioning
windowsPassword Windows Password, user settings for provisioning

Create a User For a Tenant

curl -XPOST "$serverUrl/api/accounts/2/users" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"user":{
    "username": "testuser",
    "email": "testuser@morpheusdata.com",
    "firstName": "Test",
    "lastName": "User",
    "password": "aStr0ngp@ssword",
    "roles": [{"id": 3}]
  }}'

The above command returns JSON structured like getting a single user

HTTP Request

POST $serverUrl/api/accounts/:accountId/users

URL Parameters

Parameter Description
accountId The ID of the Tenant

JSON User Parameters

The same as Create a User.

This creates a user in a specific tenant. This is only available to master tenant users with permission to manage users and tenants.

See Get Available Roles for a Sub Tenant User to find roles available to the user.

Updating a User

curl -XPUT "$serverUrl/api/users/2" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"user":{
    "username": "testUser",
    "firstName": "Jane",
    "lastName": "Doe",
    "password": "aStr0ngp@ssword",
    "roles": [{"id": 1}]
  }}'

The above command returns JSON structured like getting a single user

HTTP Request

PUT $serverUrl/api/users/:id

JSON User Parameters

Parameter Default Description
username A unique username
email The user’s email
firstName The user’s first name (optional)
lastName The user’s last name (optional)
password The password to apply to the user
roles Array of objects with id of the role(s) to assign to the user. See Get Available Roles for a User.
receiveNotifications true Receive Notifications?
linuxUsername Linux Username, user settings for provisioning
linuxPassword Linux Password, user settings for provisioning
linuxKeyPairId Linux SSH Key, user settings for provisioning
windowsUsername Windows Username, user settings for provisioning
windowsPassword Windows Password, user settings for provisioning

Update a user.

Delete a User

curl -XDELETE "$serverUrl/api/users/99" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Delete a user. This will disassociate the user from any instances they have previously provisioned.

HTTP Request

DELETE $serverUrl/api/users/:id

Get a Specific User Permissions

curl "$serverUrl/api/users/1/permissions" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "access": {
    "features": [
      {
        "id": 11,
        "code": "admin-appliance",
        "name": "Admin: Appliance Settings",
        "access": "full"
      },
      {
        "id": 13,
        "code": "admin-backupSettings",
        "name": "Admin: Backup Settings",
        "access": "none"
      }
    ],
    "zones": [
      {
        "id": 1,
        "name": "zone1",
        "access": "full"
      }
    ],
    "sites": [
      {
        "id": 2,
        "name": "aws",
        "access": "none"
      }
    ],
    "instanceTypes": [
      {
        "id": 1,
        "code": "activemq",
        "name": "ActiveMQ",
        "access": "full"
      }
    ],
    "appTemplates": [
      {
        "id": 1,
        "name": "Blank Apache",
        "access": "full"
      },
      {
        "id": 4,
        "name": "dand-azure-blueprint",
        "access": "none"
      }
    ]
  }
}

This will list all the permissions for a specific user.

HTTP Request

GET $serverUrl/api/users/:id/permissions

Get Available Roles for a User

curl "$serverUrl/api/users/available-roles" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "roles": [
     {
      "id": 1,
      "authority": "System Admin",
      "name": "System Admin",
      "description": "Super User",
      "roleType": null,
      "owner": null
    },
    {
      "id": 3,
      "authority": "User Admin",
      "name": "User Admin",
      "description": "Sub Tenant User Template",
      "roleType": "user",
      "owner": null
    }
  ]
}

This endpoint will retrieve a list of roles that can be assigned to a user.

HTTP Request

GET $serverUrl/api/accounts/available-roles

Query Parameters

Parameter Default Description
accountId (current tenant) ID of Tenant Only available to the master account.

Get Available Roles for a Sub Tenant User

curl "$serverUrl/api/users/available-roles?accountId={accountId}" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "roles": [
     {
      "id": 1,
      "authority": "System Admin",
      "name": "System Admin",
      "description": "Super User",
      "roleType": null,
      "owner": null
    },
    {
      "id": 3,
      "authority": "User Admin",
      "name": "User Admin",
      "description": "Sub Tenant User Template",
      "roleType": "user",
      "owner": null
    }
  ]
}

This endpoint will retrieve a list of roles that can be assigned to a user belonging to a sub tenant account.

NOTE Multitenant Role IDs will be different for each sub tenant account. Multitenant roles are cloned and kept in sync for each sub tenant account, so that the permissions are pruned according to the sub tenant’s assigned base role.

HTTP Request

GET $serverUrl/api/users/available-roles?accountId=:accountId

Query Parameters

Parameter Default Description
accountId (current tenant) ID of Tenant Only available to the master account.

User Settings

Provides API for managing your own user settings and api access tokens.

curl "$serverUrl/api/user-settings" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "user": {
    "id": 1,
    "username": "admin",
    "firstName": "Admin",
    "lastName": "",
    "email": "admin@morpheusdata.com",
    "linuxUsername": "morphadmin",
    "linuxPassword": "************",
    "linuxKeyPairId": null,
    "windowsUsername": "morphadmin",
    "windowsPassword": "************",
    "avatar": "$serverUrl/storage/uploads/uploads/User/1/avatar/admin_original.png",
    "desktopBackground": "$serverUrl/storage/uploads/uploads/User/1/desktopBackground/vaperwave_wallpaper_original.jpg",
    "receiveNotifications": true,
    "defaultGroup": {
      "id": 1,
      "name": "Dev Group"
    },
    "defaultCloud": {
      "id": 1,
      "name": "Dev Cloud"
    },
    "defaultPersona": {
      "id": 1,
      "code": "standard",
      "name": "Standard"
    },
    "isUsing2FA": true,
    "tenant": {
      "id": 1,
      "name": "root"
    }
  },
  "accessTokens": [
    {
      "clientId": "morph-api",
      "username": "admin",
      "expiration": "2022-03-18T14:52:02Z",
      "tokenType": "bearer",
      "maskedAccessToken": "3ae256c-********",
      "maskedRefreshToken": "465f403-********"
    },
    {
      "clientId": "morph-cli",
      "username": "admin",
      "expiration": "2022-04-01T02:29:52Z",
      "tokenType": "bearer",
      "maskedAccessToken": "10fd4a4-********",
      "maskedRefreshToken": "2341f4b-********"
    }
  ]
}

This endpoint retrieves your user settings and API access token information.

HTTP Request

GET $serverUrl/api/user-settings

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

Update User Settings

curl -XPUT "$serverUrl/api/user-settings" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "user": {
    "receiveNoticiations": true,
    "defaultGroup": {
      "id": 1
    },
    "defaultCloud": {
      "id": 1
    },
    "defaultPersona": {
      "code": "standard"
    }
  }
}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/user-settings

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

JSON Parameters

These parameters should be passed under an object called user.

Parameter Default Description
username Username
email Email
firstName First Name
lastName Last Name
password Change your password
linuxUsername Linux Username
linuxPassword Linux Password
linuxKeyPairId Linux Key Pair ID
windowsUsername Windows Username
windowsPassword Windows Password
receiveNotifications Receive Notifications (true or false)
defaultGroup.id Default Group ID
defaultCloud.id Default Cloud ID
defaultPersona.code Default Persona code, eg. standard, serviceCatalog or vdi
avatar Avatar Image File png,jpg,svg (requires Content-Type: multipart/form-data)
desktopBackground Desktop Background for VDI Persona. Image File png,jpg,svg (requires Content-Type: multipart/form-data)

Update Avatar

curl -XPOST "$serverUrl/api/user-settings/avatar" \
  -H "Authorization: BEARER $accessToken" \
  -F 'user.avatar=@filename'

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint updates your avatar image. Expects multipart form data as the request format, not JSON.

HTTP Request

POST $serverUrl/api/user-settings/avatar

HTTP Headers

Header Description
Content-Type multipart/form-data is expected.

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

Parameters

Parameter Default Description
user.avatar Image File png,jpg,svg

Delete Avatar

curl -XDELETE "$serverUrl/api/user-settings/avatar" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/user-settings/avatar

Delete your avatar image.

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

Update Desktop Background

curl -XPOST "$serverUrl/api/user-settings/desktop-background" \
  -H "Authorization: BEARER $accessToken" \
  -F 'user.desktopBackground=@filename'

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint updates your desktop background image that is used in the Virtual Desktop persona. Expects multipart form data as the request format, not JSON.

HTTP Request

POST $serverUrl/api/user-settings/desktop-background

HTTP Headers

Header Description
Content-Type multipart/form-data is expected.

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

Parameters

Parameter Default Description
user.desktopBackground Image File png,jpg,svg

Delete Desktop Background

curl -XDELETE "$serverUrl/api/user-settings/desktop-background" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Delete your desktop background image.

HTTP Request

DELETE $serverUrl/api/user-settings/desktop-background

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

Regenerate API Access Token

curl -XPUT "$serverUrl/api/user-settings/regenerate-access-token?clientId=morph-api" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/user-settings/regenerate-access-token?clientId=:clientId

Query Parameters

Parameter Default Description
clientId Client ID
userId (current user) ID of User Only available to the master tenant.

The above command returns JSON structured like this:

{
  "success": true,
  "token": "a936c304-374d-42c3-8634-8f825756d240"
}

This endpoint regenerates your API access token for the specified client. If a current token exists, it is revoked and a new token is returned.

Revoke API Access Token

curl -XPUT "$serverUrl/api/user-settings/clear-access-token?clientId=morph-api" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json"

The above command returns JSON Structured like this:

{
  "success": true
}

This endpoint revokes your API access token for the specified client.

HTTP Request

PUT $serverUrl/api/user-settings/clear-access-token?clientId=:clientId

Query Parameters

Parameter Default Description
clientId Client ID
userId (current user) ID of User Only available to the master tenant.

Get Available API Clients

curl "$serverUrl/api/user-settings/api-clients" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
    "clients": [
    {
      "clientId": "morph-api"
    },
    {
      "clientId": "morph-cli"
    }
  ]
}

This endpoint retrieves a list of available API clients.

HTTP Request

GET $serverUrl/api/user-settings/api-clients

Query Parameters

Parameter Default Description
userId (current user) ID of User Only available to the master tenant.

Identity Sources

Identity sources may be configured to allow users to authenticate with a separate service in order to gain access to the Morpheus appliance. When authenticating, Morpheus checks the credentials against the third party service and if successful will log the user into the appliance. If it’s the first time for that username, the user is created before logging in. This way users and their passwords are not managed directly in Morpheus. Each identity source has role mappings that determine the access level in Morpheus which users will receive when authenticating and successfully logging in.

The supported identity source types are LDAP (ldap), JumpCloud (jumpCloud), Active Directory (activeDirectory), Okta (okta), One Login (oneLogin), SAML (saml) and Azure SAML (azureSaml). Custom types are also supported.

An Identity Source may also be referred to as a User Source or userSource.

Get All Identity Sources

curl "$serverUrl/api/user-sources"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "userSources": [
    {
      "id": 4761,
      "name": "AD Example",
      "description": "Active Directory Example",
      "code": "vaRnweSFq",
      "type": "activeDirectory",
      "active": true,
      "deleted": false,
      "autoSyncOnLogin": true,
      "externalLogin": false,
      "allowCustomMappings": false,
      "account": {
        "id": 1552,
        "name": "Auto Tenant 1"
      },
      "defaultAccountRole": {
        "id": 19112,
        "authority": "Default: User"
      },
      "config": {
        "url": "10.10.20.1",
        "domain": "qa.ad.myorg.com",
        "useSSL": "off",
        "bindingUsername": "admin",
        "bindingPassword": "************",
        "requiredGroup": "MyOrgUsers",
        "searchMemberGroups": true,
        "requiredGroupDN": "CN=MyOrgUsers,CN=Users,DC=qa,DC=ad,DC=myorg,DC=com"
      },
      "roleMappings": [
        {
          "sourceRoleName": "Mathematicians",
          "sourceRoleFqn": "CN=Mathematicians,CN=Users,DC=qa,DC=ad,DC=myorg,DC=com",
          "mappedRole": {
            "id": 19117,
            "authority": "Sub Role"
          }
        }
      ],
      "subdomain": "auto",
      "loginURL": "https://dev.myorg.com/login/account/auto",
      "providerSettings": {
      },
      "dateCreated": "2020-02-06T17:00:13Z",
      "lastUpdated": "2021-01-30T08:54:21Z"
    },


    {
      "id": 5400,
      "name": "FreeIPA LDAP",
      "description": null,
      "code": "uciTGxHGT",
      "type": "ldap",
      "active": false,
      "deleted": false,
      "autoSyncOnLogin": true,
      "externalLogin": false,
      "allowCustomMappings": false,
      "account": {
        "id": 1633,
        "name": "ctaylor"
      },
      "defaultAccountRole": {
        "id": 24436,
        "authority": "A Persona User Role"
      },
      "config": {
        "url": "ldaps://gw-freeipa.prod.den.myorg.com:636",
        "bindingUsername": "admin",
        "bindingPassword": "************",
        "userFqnExpression": "uid=$username,cn=users,cn=accounts,dc=prod,dc=den,dc=myorg,dc=com",
        "requiredRoleFqn": "cn=ipausers,cn=groups,cn=accounts,dc=prod,dc=den,dc=myorg,dc=com",
        "usernameAttribute": "",
        "commonNameAttribute": "",
        "firstNameAttribute": "",
        "lastNameAttribute": "",
        "emailAttribute": "",
        "uniqueMemberAttribute": "",
        "memberOfAttribute": "memberOf"
      },
      "roleMappings": [

      ],
      "subdomain": "ctaylor",
      "loginURL": "https://dev.myorg.com/login/account/ctaylor",
      "providerSettings": {
      },
      "dateCreated": "2021-01-07T09:03:52Z",
      "lastUpdated": "2021-01-07T18:07:37Z"
    },
    {
      "id": 4771,
      "name": "Jump Cloud QA",
      "description": "jumpcloud trial",
      "code": "E81DYhKVN",
      "type": "jumpCloud",
      "active": true,
      "deleted": false,
      "autoSyncOnLogin": true,
      "externalLogin": false,
      "allowCustomMappings": false,
      "account": {
        "id": 1552,
        "name": "Auto Tenant 1"
      },
      "defaultAccountRole": {
        "id": 19112,
        "authority": "Default: User"
      },
      "config": {
        "organizationId": "22ba1130591be3786b2343a1",
        "bindingUsername": "jcgauss",
        "bindingPassword": "************",
        "requiredRole": "MyOrgTag"
      },
      "roleMappings": [
        {
          "sourceRoleName": "mathematicians",
          "sourceRoleFqn": "cn=mathematicians,ou=Users,o=56ba8430591be3786b2343b0,dc=jumpcloud,dc=com",
          "mappedRole": {
            "id": 19117,
            "authority": "Sub Role"
          }
        }
      ],
      "subdomain": "auto",
      "loginURL": "https://dev.myorg.com/login/account/auto",
      "providerSettings": {
      },
      "dateCreated": "2020-02-06T17:52:07Z",
      "lastUpdated": "2021-01-30T10:41:52Z"
    },
    {
      "id": 4782,
      "name": "Okta QA",
      "description": "oktapreview trial",
      "code": "eZiReLj9W",
      "type": "okta",
      "active": true,
      "deleted": false,
      "autoSyncOnLogin": true,
      "externalLogin": false,
      "allowCustomMappings": false,
      "account": {
        "id": 1552,
        "name": "Auto Tenant 1"
      },
      "defaultAccountRole": {
        "id": 19112,
        "authority": "Default: User"
      },
      "config": {
        "url": "https://dev-911522.oktapreview.com",
        "administratorAPIToken": "************",
        "requiredGroup": "myorg",
        "requiredGroupId": "00g88dvxc64kvt6UR0h7"
      },
      "roleMappings": [
        {
          "sourceRoleName": "mathematicians",
          "sourceRoleFqn": "00g86tlvyuJlw3OqZ0h7",
          "mappedRole": {
            "id": 19117,
            "authority": "Sub Role"
          }
        }
      ],
      "subdomain": "auto",
      "loginURL": "https://dev.myorg.com/login/account/auto",
      "providerSettings": {
      },
      "dateCreated": "2020-02-06T18:16:40Z",
      "lastUpdated": "2021-01-30T09:40:35Z"
    },
    {
      "id": 4783,
      "name": "OneLogin QA",
      "description": "onelogin test",
      "code": "stfG0VlIT",
      "type": "oneLogin",
      "active": true,
      "deleted": false,
      "autoSyncOnLogin": true,
      "externalLogin": false,
      "allowCustomMappings": false,
      "account": {
        "id": 1552,
        "name": "Auto Tenant 1"
      },
      "defaultAccountRole": {
        "id": 19112,
        "authority": "Default: User"
      },
      "config": {
        "subdomain": "myorg-labs-dev",
        "region": "us",
        "clientSecret": "************",
        "clientId": "3c9f6960b4dd8af33dfd7e8022569a095c3d09256657082ea03d40f6b1583260",
        "requiredRole": "Admin Role",
        "requiredRoleId": "144498"
      },
      "roleMappings": [
        {
          "sourceRoleName": "Mathematician Role",
          "sourceRoleFqn": "145780",
          "mappedRole": {
            "id": 19117,
            "authority": "Sub Role"
          }
        }
      ],
      "subdomain": "auto",
      "loginURL": "https://dev.myorg.com/login/account/auto",
      "providerSettings": {
      },
      "dateCreated": "2020-02-06T18:16:46Z",
      "lastUpdated": "2021-01-30T09:09:45Z"
    },
    {
      "id": 207,
      "name": "OneLogin SAML",
      "description": "saml test",
      "code": "cD9bPD9oa",
      "type": "saml",
      "active": false,
      "deleted": false,
      "autoSyncOnLogin": true,
      "externalLogin": true,
      "allowCustomMappings": false,
      "account": {
        "id": 1,
        "name": "MyOrg QA"
      },
      "defaultAccountRole": {
        "id": 17,
        "authority": "Default: User"
      },
      "config": {
        "roleAttributeName": "firstName",
        "requiredAttributeValue": "Carl",
        "givenNameAttribute": "firstName",
        "surnameAttribute": "lastName",
        "logoutUrl": "https://myorg-dev.onelogin.com/trust/saml2/http-redirect/slo/618040",
        "doNotIncludeSAMLRequest": false,
        "emailAttribute": "email",
        "url": "https://myorg-dev.onelogin.com/trust/saml2/http-post/sso/618040",
        "doNotValidateSignature": false,
        "doNotValidateStatusCode": false,
        "doNotValidateDestination": false,
        "doNotValidateIssueInstants": false,
        "doNotValidateAssertions": false,
        "doNotValidateAuthStatements": false,
        "doNotValidateSubject": false,
        "doNotValidateConditions": false,
        "doNotValidateAudiences": false,
        "doNotValidateSubjectRecipients": false,
        "SAMLSignatureMode": "SelfSigned"
      },
      "roleMappings": [
        {
          "sourceRoleName": "Carl",
          "sourceRoleFqn": null,
          "mappedRole": {
            "id": 2486,
            "authority": "Sub Admin"
          }
        }
      ],
      "subdomain": "1",
      "loginURL": "https://dev.myorg.com/login/account/1",
      "providerSettings": {
        "entityId": "https://dev.myorg.com/saml/cD9bPD9oa",
        "acsUrl": "https://dev.myorg.com/externalLogin/callback/cD9bPD9oa",
        "spMetadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><EntityDescriptor entityID=\"https://dev.myorg.com/saml/cD9bPD9oa\" xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\"><SPSSODescriptor AuthnRequestsSigned=\"true\" WantAssertionsSigned=\"true\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat><AssertionConsumerService index=\"0\" isDefault=\"true\" Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://dev.myorg.com/externalLogin/callback/cD9bPD9oa\"/></SPSSODescriptor></EntityDescriptor>"
      },
      "dateCreated": "2017-05-24T03:52:51Z",
      "lastUpdated": "2021-01-30T10:58:16Z"
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 11,
    "total": 11
  }
}

This endpoint retrieves all identity sources. The master tenant will see identity sources for all tenants.

HTTP Request

GET $serverUrl/api/user-sources

Query Parameters

Parameter Default Description
phrase Filter on wildcard match of name or description
name Filter on exact match of name
type Filter on exact match of type code
accountId Filter on a Tenant ID. Only available to the master tenant.

Get a Specific Identity Source

curl "$serverUrl/api/user-sources/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "userSource": {
    "id": 4761,
    "name": "AD Example",
    "description": "Example AD",
    "code": "vaRnweSFq",
    "type": "activeDirectory",
    "active": true,
    "deleted": false,
    "autoSyncOnLogin": true,
    "externalLogin": false,
    "allowCustomMappings": false,
    "account": {
      "id": 1552,
      "name": "Auto Tenant 1"
    },
    "defaultAccountRole": {
      "id": 19112,
      "authority": "Default: User"
    },
    "config": {
      "url": "10.10.20.1",
      "domain": "qa.ad.myorg.com",
      "useSSL": "off",
      "bindingUsername": "admin",
      "bindingPassword": "************",
      "requiredGroup": "MyOrgUsers",
      "searchMemberGroups": true,
      "requiredGroupDN": "CN=MyOrgUsers,CN=Users,DC=qa,DC=ad,DC=myorg,DC=com"
    },
    "roleMappings": [
      {
        "sourceRoleName": "Mathematicians",
        "sourceRoleFqn": "CN=Mathematicians,CN=Users,DC=qa,DC=ad,DC=myorg,DC=com",
        "mappedRole": {
          "id": 19117,
          "authority": "Sub Role"
        }
      }
    ],
    "subdomain": "auto",
    "loginURL": "https://dev.myorg.com/login/account/auto",
    "providerSettings": {
    },
    "dateCreated": "2020-02-06T17:00:13Z",
    "lastUpdated": "2021-01-30T08:54:21Z"
  }
}

This endpoint retrieves a specific identity source.

HTTP Request

GET $serverUrl/api/user-sources/:id

URL Parameters

Parameter Description
ID The ID of the identity source

Create an Identity Source

curl -XPOST "$serverUrl/api/accounts/60/user-sources" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "userSource": {
    "type": "activeDirectory",
    "name": "Ninja AD",
    "config": {
      "url": "10.10.10.22",
      "domain": "ad.morpheusdata.com",
      "useSSL": "on",
      "bindingUsername": "adadmin",
      "bindingPassword": "96119ec75001",
      "requiredGroup": "MyOrgUsers",
      "searchMemberGroups": false
    },
    "defaultAccountRole": {
      "id": 19
    }
  }
}'

The above command returns JSON structured like getting a single identity source:

HTTP Request

POST $serverUrl/api/accounts/:accountId/user-sources

URL Parameters

Parameter Description
accountId The ID of the subtenant account to associate the identity source with

JSON Parameters

Parameter Default Description
name Name
type Type code (ldap, jumpCloud, activeDirectory, okta, oneLogin, saml, customExternal, customApi)
description Description (optional)
defaultAccountRole.id Default Role ID
roleMappings Map of Morpheus Role ID : Fully Qualified Role Name
roleMappingNames Map of Morpheus Role ID : Role Name
config Map of configuration options which vary by type.

JSON Parameters for ldap

Parameter Default Description
config.url URL
config.bindingUsername Binding Username
config.bindingPassword Binding Password
config.requiredGroup Required group name (a.k.a. tag)
config.userFqnExpression User DN Expression eg. uid=$username,cn=users,cn=account,dc=example,dc=veritas,dc=com

JSON Parameters for jumpCloud

Parameter Default Description
config.organizationId false Organization ID
config.bindingUsername Binding Username
config.bindingPassword Binding Password
config.requiredRole Required group name (a.k.a. tag)

JSON Parameters for activeDirectory

Parameter Default Description
config.url AD Server
config.domain Domain
config.useSSL false Use SSL
config.bindingUsername Binding Username
config.bindingPassword Binding Password
config.requiredGroup Required Group
config.searchMemberGroups Include Member Groups

JSON Parameters for okta

Parameter Default Description
config.url OKTA URL
config.administratorAPIToken Adminstrator API Token
config.requiredGroup Required Group

JSON Parameters for oneLogin

Parameter Default Description
config.subdomain OneLogin Subdomain
config.region OneLogin Region
config.clientSecret API Client Secret
config.clientId API Client ID
config.requiredRole Required Role

JSON Parameters for saml

Parameter Default Description
config.url Login Redirect URL
config.doNotIncludeSAMLRequest false Exclude SAMLRequest Parameter
config.logoutUrl Logout Post URL
config.publicKey Signing Public Key

JSON Parameters for customExternal

Parameter Default Description
config.loginUrl External Login URL
config.doNotIncludeSAMLRequest false Do not include SAMLRequest
config.logout External Logout URL
config.encryptionAlgo Encryption Algorithm (‘NONE’,'AES’,'DES’,'DESede’,'HmacSHA1’, 'HmacSHA256’)
config.encryptionKey Encryption Key

JSON Parameters for customApi

Parameter Default Description
config.endpoint API Endpoint
config.apiStyle API Style ('Form URL Encoded [GET]’,'Form URL Encoded [POST]’,'JSON [POST]’,'XML [POST]’,'HTTP Basic [GET]’)
config.encryptionAlgo Encryption Algorithm ('NONE’,'AES’,'DES’,'DESede’,'HmacSHA1’, 'HmacSHA256’)
config.encryptionKey Encryption Key

Updating an Identity Source

curl -XPUT "$serverUrl/api/user-sources/3" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "userSource": {
    "type": "activeDirectory",
    "name": "Ninja AD",
    "config": {
      "url": "10.10.10.22",
      "domain": "ad.morpheusdata.com",
      "useSSL": "on",
      "bindingUsername": "adadmin",
      "bindingPassword": "96119ec75001",
      "requiredGroup": "MyOrgUsers",
      "searchMemberGroups": "off"
    },
    "defaultAccountRole": {
      "id": 19
    }
  }
}'

The above command returns JSON structured like getting a single identity source:

HTTP Request

PUT $serverUrl/api/user-sources/:id

URL Parameters

Parameter Description
ID The ID of the identity source

JSON Parameters

Parameter Default Description
name Name
description Description (optional)
active Activate (true) or disable (false) the identity source
defaultAccountRole.id Default Role ID
roleMappings Map of Morpheus Role ID : Fully Qualified Role Name
roleMappingNames Map of Morpheus Role ID : Role Name
config Map of configuration options which vary by type.

Updating Subdomain for an Identity Source

curl -XPUT "$serverUrl/api/user-sources/3/subdomain" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "ninjas"}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/user-sources/:id/subdomain

URL Parameters

Parameter Description
ID The ID of the user source

JSON Parameters

Parameter Default Description
subdomain New Subdomain for account

This endpoint updates the subdomain for the account associated with the user source.

Delete an Identity Source

curl -XDELETE "$serverUrl/api/user-sources/3" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/user-sources/:id

URL Parameters

Parameter Description
ID The ID of the user source

Will delete an identity source from the system and make it no longer usable.

Service Plans

Provides API interfaces for managing service plans within Morpheus.

Get All Service Plans

curl "$serverUrl/api/service-plans" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "servicePlans": [
    {
      "id": 1,
      "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory",
      "code": "amazon-t2.nano",
      "active": true,
      "sortOrder": 0,
      "description": "Amazon T2 Nano - 1 Core, 0.5GB Memory",
      "maxStorage": 10737418240,
      "maxMemory": 536870912,
      "maxCpu": null,
      "maxCores": 1,
      "maxDisks": null,
      "customCpu": true,
      "customCores": true,
      "customMaxStorage": true,
      "customMaxDataStorage": true,
      "customMaxMemory": true,
      "addVolumes": true,
      "memoryOptionSource": null,
      "cpuOptionSource": null,
      "dateCreated": "2019-07-23T00:38:02+0000",
      "lastUpdated": "2019-07-23T00:38:02+0000",
      "regionCode": null,
      "visibility": "public",
      "editable": false,
      "provisionType": {
        "id": 6,
        "name": "Amazon",
        "code": "amazon",
        "rootDiskCustomizable": true,
        "addVolumes": true,
        "customizeVolume": true,
        "hasConfigurableCpuSockets": false
      },
      "tenants": "",
      "priceSets": [
        {
          "id": 43,
          "name": "Amazon - t2.nano - US West (N. California)",
          "code": "amazon.t2.nano.ec2.us-west-1.amazonaws.com",
          "priceUnit": "hour"
        }
      ],
      "config": {
      },
      "zones": [
        {
          "id": 3,
          "name": "dans aws cloud",
          "code": "dans_aws_cloud"
        },
        {
          "id": 5,
          "name": "dans aws cloud 2",
          "code": "amazon"
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 184,
    "max": 1,
    "offset": 0
  }
}

This endpoint retrieves all service plans.

HTTP Request

GET $serverUrl/api/service-plans

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, description and provision type name, restricts query to only load service plans which contain the phrase specified
includeZones false Indicates including zones in the service plan response payload
provisionTypeId Provision type filter, restricts query to only load service plans of specified provision type
includeInactive false Can be used to include inactive service plans

Get a Specific Service Plan

curl "$serverUrl/api/service-plans/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "servicePlan": {
    "id": 1,
    "name": "Amazon T2 Nano - 1 Core, 0.5GB Memory",
    "code": "amazon-t2.nano",
    "active": true,
    "sortOrder": 0,
    "description": "Amazon T2 Nano - 1 Core, 0.5GB Memory",
    "maxStorage": 10737418240,
    "maxMemory": 536870912,
    "maxCpu": null,
    "maxCores": 1,
    "maxDisks": null,
    "customCpu": true,
    "customCores": true,
    "customMaxStorage": true,
    "customMaxDataStorage": true,
    "customMaxMemory": true,
    "addVolumes": true,
    "memoryOptionSource": null,
    "cpuOptionSource": null,
    "dateCreated": "2019-07-23T00:38:02+0000",
    "lastUpdated": "2019-07-23T00:38:02+0000",
    "regionCode": null,
    "visibility": "public",
    "editable": false,
    "provisionType": {
      "id": 6,
      "name": "Amazon",
      "code": "amazon",
      "rootDiskCustomizable": true,
      "addVolumes": true,
      "customizeVolume": true,
      "hasConfigurableCpuSockets": false
    },
    "tenants": "",
    "priceSets": [
      {
        "id": 43,
        "name": "Amazon - t2.nano - US West (N. California)",
        "code": "amazon.t2.nano.ec2.us-west-1.amazonaws.com",
        "priceUnit": "hour"
      }
    ],
    "config": {
    },
    "zones": [
      {
        "id": 3,
        "name": "dans aws cloud",
        "code": "dans_aws_cloud"
      },
      {
        "id": 5,
        "name": "dans aws cloud 2",
        "code": "amazon"
      }
    ],
    "permissions": {
    }
  }
}

This endpoint retrieves a specific service plan.

HTTP Request

GET $serverUrl/api/service-plans/:id

URL Parameters

Parameter Description
id ID of the service plan

Create a Service Plan

Use this command to create a service plan.

curl -XPOST "$serverUrl/api/service-plans" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"servicePlan": {
        "name": "stubby toes plan 1",
        "code": "stubby.toes.plan.1",
        "description": null,
        "provisionType": {
          "id": 1
        },
        "customCores": true,
        "config": {
          "ranges": {
              "maxStorage": null,
              "minMemory": 1073741824,
              "maxMemory": 1073741824,
              "minCores": 1,
              "maxCores": 4
          }
        },
        "maxStorage": 1073741824,
        "maxMemory": 1073741824,
        "priceSets": [
          {
              "id": 43
          }
        ],
        "visibility": "private",
        "permissions": {
          "resourcePermissions": {
              "all": true,
              "sites": [
                  {
                      "id": 4,
                      "default": true
                  }
              ]
          },
          "tenantPermissions": {
              "accounts": [
                  1,
                  2
              ]
          }
        }
      }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/service-plans

JSON Parameters

Parameter Required Description
name Y Service plan name
code Y Service plan code, must be unique
description N Service plan description
editable N Can be used to enable / disable the editability of the service plan. Default is on
maxStorage Y Max storage size in bytes
maxMemory Y Max memory size in bytes
maxCores N Max cores
maxDisks N Max disks allowed
provisionType.id Y Provision type ID
customCores N Can be used to enable / disable customizable cores. Default is off
customMaxStorage N Can be used to enable / disable customizable storage. Default is off
customMaxDataStorage N Can be used to enable / disable customizable extra volumes. Default is off
customMaxMemory N Can be used to enable / disable customizable memory. Default is off
addVolumes N Can be used to enable / disable ability to add volumes. Default is off
sortOrder N Sort order
priceSets.id N List of price sets to include in service plan
config.ranges N Key for service plan custom configuration, see Config

Config

The config parameter is for custom ranges for the service plan.

Parameter Required Description
storageSizeType N Specifies range min / max storage multiplier [gb, mb]. Defaults to gb
memorySizeType N Specifies range min / max memory multiplier [mb, gb]. Defaults to mb.
range.minStorage N Custom min storage in GB (unless storageSizeType set to mb)
range.maxStorage N Custom max storage in GB (unless storageSizeType set to mb)
range.minMemory N Custom min memory in bytes
range.maxMemory N Custom max memory in bytes
range.minCores N Custom min cores
range.maxCores N Custom max cores

Update a Service Plan

curl -XPUT "$serverUrl/api/service-plans/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"servicePlan": {  
      "name": "stubby toes plan 1",
      "code": "stubby.toes.plan.1",
      "description": null,
      "maxStorage": 10737418240,
      "config": {
        "storageSizeType": "gb",
        "memorySizeType": "mb",
        "ranges": {
          "minStorage": 1000,
          "maxStorage": 100000,
          "minMemory": 536870912,
          "maxMemory": 1073741824,
          "minCores": 1,
          "maxCores": 3
        }
      },
      "maxMemory": 536870912,
      "maxCores": 3,
      "maxDisks": 5,
      "customCores": true,
      "customMaxStorage": true,
      "customMaxDataStorage": true,
      "customMaxMemory": true,
      "sortOrder": 5,
      "priceSets": [
        {
          "id": 170
        }
      ],
      "addVolumes": true,
      "provisionType": {
        "id": 1
      },
      "visibility": "private",
      "permissions": {
        "resourcePermissions": {
          "all": true,
          "sites": [
            {
              "id": 2
            },
            {
              "id": 4
            }
          ]
        },
        "tenantPermissions": {
          "accounts": [
            1
          ]
        }
      }
    }}

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/service-plans/:id

URL Parameters

Parameter Description
id The ID of the service plan

JSON Parameters

Parameter Required Description
name Y Service plan name
code Y Service plan code, must be unique
description N Service plan description
maxStorage Y Max storage size in bytes
maxMemory Y Max memory size in bytes
maxCores N Max cores
maxDisks N Max disks allowed
provisionType.id Y Provision type ID
customCores N Can be used to enable / disable customizable cores. Default is off
customMaxStorage N Can be used to enable / disable customizable storage. Default is off
customMaxDataStorage N Can be used to enable / disable customizable extra volumes. Default is off
customMaxMemory N Can be used to enable / disable customizable memory. Default is off
addVolumes N Can be used to enable / disable ability to add volumes. Default is off
sortOrder N Sort order
priceSets.id N List of price sets to include in service plan
config.ranges N Key for service plan custom configuration, see Config

Activate a Service Plan

curl -XPUT "$serverUrl/api/service-plans/1/activate" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will activate a service plan

HTTP Request

PUT $serverUrl/api/service-plans/:id/activate

URL Parameters

Parameter Description
id The ID of the service plan

Deactivate a Service Plan

curl -XPUT "$serverUrl/api/service-plans/1/deactivate" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will deactivate a service plan

HTTP Request

PUT $serverUrl/api/service-plans/:id/deactivate

URL Parameters

Parameter Description
id The ID of the service plan

Price Sets

Provides API interfaces for managing price sets within Morpheus.

Get All Price Sets

curl "$serverUrl/api/price-sets" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "priceSets": [
    {
      "id": 25,
      "name": "Amazon - c1.medium - US West (N. California)",
      "code": "amazon.c1.medium.ec2.us-west-1.amazonaws.com",
      "active": true, 
      "priceUnit": "hour",
      "type": "compute_plus_storage",
      "regionCode": "ec2.us-west-1.amazonaws.com",
      "systemCreated": false,
      "zone": null,
      "zonePool": null,
      "account": null,
      "prices": [
        {
          "id": 3,
          "name": "Amazon - EBS (gp2) - US West (N. California)",
          "code": "amazon.storage.ebs.ec2.us-west-1.amazonaws.com",
          "priceType": "storage",
          "priceUnit": "month",
          "additionalPriceUnit": "GB",
          "price": 0.12,
          "customPrice": 0.0,
          "markupType": null,
          "markup": 0.0,
          "markupPercent": 0.0,
          "cost": 0.12,
          "currency": "usd",
          "incurCharges": "always",
          "platform": null,
          "software": null,
          "volumeType": {
            "id": 10,
            "code": "amazon-gp2",
            "name": "gp2"
          },
          "datastore": null,
          "crossCloudApply": null,
          "account": null
        }
      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 169,
    "offset": 0,
    "max": 1
  }
}

This endpoint retrieves all price sets.

HTTP Request

GET $serverUrl/api/price-sets

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load price sets with name or code containing the phrase specified
includeInactive false If true, include inactive prices in the results

Get a Specific Price Set

curl "$serverUrl/api/price-sets/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "priceSet": {
    "id": 25,
    "name": "Amazon - c1.medium - US West (N. California)",
    "code": "amazon.c1.medium.ec2.us-west-1.amazonaws.com",
    "active": true, 
    "priceUnit": "hour",
    "type": "compute_plus_storage",
    "regionCode": "ec2.us-west-1.amazonaws.com",
    "systemCreated": false,
    "zone": null,
    "zonePool": null,
    "account": null,
    "prices": [
      {
        "id": 3,
        "name": "Amazon - EBS (gp2) - US West (N. California)",
        "code": "amazon.storage.ebs.ec2.us-west-1.amazonaws.com",
        "priceType": "storage",
        "priceUnit": "month",
        "additionalPriceUnit": "GB",
        "price": 0.12,
        "customPrice": 0.0,
        "markupType": null,
        "markup": 0.0,
        "markupPercent": 0.0,
        "cost": 0.12,
        "currency": "usd",
        "incurCharges": "always",
        "platform": null,
        "software": null,
        "volumeType": {
          "id": 10,
          "code": "amazon-gp2",
          "name": "gp2"
        },
        "datastore": null,
        "crossCloudApply": null,
        "account": null
      }
    ]
  }
}

This endpoint retrieves a specific price set.

HTTP Request

GET $serverUrl/api/price-sets/:id

URL Parameters

Parameter Description
id ID of the price set

Create a Price Set

Use this command to create a price set.

curl -XPOST "$serverUrl/api/price-sets" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"priceSet": {
        "name": "price set 1",
        "code": "price.set.1",
        "regionCode": "region.code.1",
        "zone": {
          "id": 3
        },
        "zonePool": {
          "id": 7
        },
        "priceUnit": "hour",
        "type": "compute_plus_storage",
        "prices": [
          {
            "id": 409
          },
          {
            "id": 124
          }
        ]
     }}'

The above command returns JSON Structured like this:

{
  "success": true,
  "id": 1
}

HTTP Request

POST $serverUrl/api/price-sets

JSON Parameters

Parameter Required Description
name Y Price set name
code Y Price set code, must be unique
regionCode N Price set region code
zone.id N Cloud ID
zonePool.id N Resource pool ID
priceUnit Y Price unit: minute, hour, day, month, year, two year, three year, four year, five year
type Y Price set type: fixed, compute_plus_storage, component
prices N List of price IDs to associate with price set

Update a Price Set

curl -XPUT "$serverUrl/api/price-sets/1" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{"priceSet": {
          "name": "new price set name",
          "restartUsage": true,
          "prices": [
            {
              "id": 409
            },
            {
              "id": 124
            }
          ]
        }
      }

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/price-sets/:id

URL Parameters

Parameter Description
id The ID of the price set

JSON Parameters

Parameter Required Description
name N Price set new name
restartUsage N Can be used to apply price changes to usage: true, false
prices N List of price IDs to associate with price set

Deactivate a Price Set

curl -XPUT "$serverUrl/api/price-sets/1/deactivate" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will deactivate a price set

HTTP Request

PUT $serverUrl/api/price-sets/:id/deactivate

URL Parameters

Parameter Description
id The ID of the price set

Prices

Provides API interfaces for managing prices within Morpheus.

Get All Prices

curl "$serverUrl/api/prices" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "prices": [
    {
      "id": 124,
      "name": "Amazon - c1.medium - US West (N. California) - Linux",
      "code": "amazon.c1.medium.ec2.us-west-1.amazonaws.com.Linux",
      "active": true,
      "priceType": "compute",
      "priceUnit": "hour",
      "additionalPriceUnit": null,
      "price": 0.148,
      "customPrice": 0.0,
      "markupType": null,
      "markup": 0.0,
      "markupPercent": 0.0,
      "cost": 0.148,
      "currency": "usd",
      "incurCharges": "running",
      "platform": "Linux",
      "software": null,
      "volumeType": null,
      "datastore": null,
      "crossCloudApply": null,
      "account": null
    }
  ],
  "meta": {
    "size": 1,
    "total": 411,
    "offset": 0,
    "max": 1
  }
}

This endpoint retrieves all prices.

HTTP Request

GET $serverUrl/api/prices

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Restricts query to only load prices with name or code containing the phrase specified
includeInactive false If true, include inactive prices in the results
priceType Restricts query to only load only prices with specified priceType
platform Restricts query to only load only prices with specified platform
currency Restricts query to only load only prices with specified currency

Get a Specific Price

curl "$serverUrl/api/prices/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "price": {
    "id": 124,
    "name": "Amazon - c1.medium - US West (N. California) - Linux",
    "code": "amazon.c1.medium.ec2.us-west-1.amazonaws.com.Linux",
    "active": true,
    "priceType": "compute",
    "priceUnit": "hour",
    "additionalPriceUnit": null,
    "price": 0.148,
    "customPrice": 0.0,
    "markupType": null,
    "markup": 0.0,
    "markupPercent": 0.0,
    "cost": 0.148,
    "currency": "usd",
    "incurCharges": "running",
    "platform": "Linux",
    "software": null,
    "volumeType": null,
    "datastore": null,
    "crossCloudApply": null,
    "account": null
  }
}

This endpoint retrieves a specific price.

HTTP Request

GET $serverUrl/api/prices/:id

URL Parameters

Parameter Description
id ID of the price

Create a Price

Use this command to create a price.

curl -XPOST "$serverUrl/api/prices" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "price": {
          "name": "dan",
          "code": "dan",
          "account": {
            "id": 1
          },
          "priceType": "fixed",
          "priceUnit": "month",
          "incurCharges": "running",
          "currency": "USD",
          "cost": 10.5,
          "markupType": "fixed",
          "markup": 1.25
        }
      }'

The above command returns JSON Structured like this:

{
  "success": true,
  "id": 1
}

HTTP Request

POST $serverUrl/api/prices

JSON Parameters

Parameter Required Description
name Y Price name
code Y Price code, must be unique
account.id N Assign to specified tenant account
priceType Y Price type code, see Price Types
priceUnit Y Price unit: minute, hour, day, month, year, two year, three year, four year, five year
incurCharges Y Indicates when to incur charges: running, stopped, always
currency Y ISO Currency code
cost Y Cost
markupType N Price adjustment type: fixed, percent, custom
markup N Amount for fixed price adjustment type
markupPercent N Percent for percent price adjustment type
customPrice N Custom price for custom price adjustment type
platform N Platform, required for platform price type
software N Software, required for software price type
volumeType.id N Volume type ID, required for storage price type. The endpoint /api/prices/volume-types provides a list of available volume type options.
datastore.id N Datastore ID, required for datastore price type
crossCloudApply N Apply price across clouds, optional true/false flag for datastore price type

Price Types

Type Code
Everything fixed
Memory + CPU compute
Memory Only memory
Cores Only cores
Disk Only storage
Datastore datastore
Platform platform
Software software

Update a Price

curl -XPUT "$serverUrl/api/prices/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "price": {
          "name": "dan",
          "code": "dan",
          "account": {
            "id": 1
          },
          "priceType": "fixed",
          "priceUnit": "month",
          "incurCharges": "running",
          "currency": "USD",
          "cost": 10.5,
          "markupType": "fixed",
          "markup": 1.25
        }
      }'

The above command returns JSON structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/prices/:id

URL Parameters

Parameter Description
id The ID of the price

JSON Parameters

Parameter Required Description
name Y Price name
priceType Y Price type code, see Price Types
priceUnit Y Price unit: minute, hour, day, month, year, two year, three year, four year, five year
incurCharges Y Indicates when to incur charges: running, stopped, always
currency Y ISO Currency code
cost Y Cost
markupType N Price adjustment type: fixed, percent, custom
markup N Amount for fixed price adjustment type
markupPercent N Percent for percent price adjustment type
customPrice N Custom price for custom price adjustment type
platform N Platform, required for platform price type
software N Software, required for software price type
volumeType.id N Volume type ID, required for storage price type
datastore.id N Datastore ID, required for datastore price type
crossCloudApply N Apply price across clouds, optional true, false flag for datastore price type
restartUsage N Apply changes to usage

Deactivate a Price

curl -XDELETE "$serverUrl/api/prices/1/deactivate" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will deactivate a price

HTTP Request

PUT $serverUrl/api/prices/:id/deactivate

URL Parameters

Parameter Description
id The ID of the price

Integrations

Provides API interfaces for managing integrations within Morpheus.

Get All Integrations

curl "$serverUrl/api/integrations" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "integrations": [
    {
      "id": 6448,
      "name": "Ansible",
      "enabled": true,
      "type": "ansible",
      "integrationType": {
        "id": 3,
        "code": "ansible",
        "name": "Ansible"
      },
      "url": "git@github.com:organization/ansible.git",
      "isPlugin": false,
      "config": {
        "cm": {
          "ansiblePlaybooks": "/",
          "ansibleRoles": "/roles",
          "ansibleGroupVars": "/vars",
          "ansibleHostVars": "/hosts",
          "ansibleCommandBus": "on",
          "ansibleVerbose": "on",
          "ansibleGalaxyEnabled": null,
          "cacheEnabled": true
        }
      },
      "status": "ok",
      "statusDate": "2021-03-19T20:09:27Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 1257,
      "name": "Github - Neo",
      "enabled": true,
      "type": "github",
      "integrationType": {
        "id": 15,
        "code": "github",
        "name": "GitHub"
      },
      "username": "neo",
      "serviceKey": {
        "id": 3,
        "name": "Neo"
      },
      "serviceMode": "static",
      "isPlugin": false,
      "config": {
        "defaultBranch": "",
        "cacheEnabled": true
      },
      "status": "ok",
      "statusDate": "2021-03-19T20:09:30Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 4997,
      "name": "Labs Ansible Tower",
      "enabled": true,
      "type": "ansibleTower",
      "integrationType": {
        "id": 25,
        "code": "ansibleTower",
        "name": "Ansible Tower"
      },
      "url": "https://10.0.0.91",
      "username": "admin",
      "password": "************",
      "version": "v2",
      "isPlugin": false,
      "config": {
      },
      "status": "ok",
      "statusDate": "2021-04-24T03:47:13Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 9471,
      "name": "Labs BlueCat",
      "enabled": true,
      "type": "bluecat",
      "integrationType": {
        "id": 17,
        "code": "bluecat",
        "name": "Bluecat"
      },
      "url": "https://10.0.0.99",
      "port": "22",
      "username": "neo",
      "password": "************",
      "serviceMode": "static",
      "isPlugin": false,
      "config": {
      },
      "status": "ok",
      "statusDate": null,
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 4343,
      "name": "Labs Cherwell",
      "enabled": true,
      "type": "cherwell",
      "integrationType": {
        "id": 26,
        "code": "cherwell",
        "name": "Cherwell"
      },
      "url": "https://cherwell-host",
      "username": "CSDAdmin",
      "password": "************",
      "isPlugin": false,
      "config": {
        "cherwellCustomCmdbMapping": "{\r\n\"ShortDescription\":\"Created by ${instance.createdByUsername} in ${zone.name}\"\r\n}",
        "cherwellClientKey": "a1063167-24e6-46a0-8b1e-6316ff3080be",
        "cherwellCreatedBy": "Jamie Young",
        "cherwellStartDate": "5",
        "cherwellEndDate": "10",
        "cherwellIgnoreSSLErrors": null,
        "cherwellBusinessObject": ""
      },
      "status": "ok",
      "statusDate": null,
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 9377,
      "name": "Labs Infoblox - H5",
      "enabled": true,
      "type": "infoblox",
      "integrationType": {
        "id": 16,
        "code": "infoblox",
        "name": "Infoblox"
      },
      "url": "https://infoblox-host/wapi/v2.9",
      "port": "22",
      "username": "admin",
      "password": "************",
      "serviceMode": "static",
      "isPlugin": false,
      "config": {
        "_inventoryExisting": "",
        "inventoryExisting": "on",
        "extraAttributes": "{\r\n\"Date Assigned\":\"\<\%\=dateCreated%>\",\r\n\"Requestor\":\"\<\%\=username%>\",\r\n\"Request Number\":\"\<\%\=userId%>\"\r\n}"
      },
      "status": "ok",
      "statusDate": "2021-04-24T03:00:05Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 933,
      "name": "Labs Jenkins",
      "enabled": true,
      "type": "jenkins",
      "integrationType": {
        "id": 14,
        "code": "jenkins",
        "name": "Jenkins"
      },
      "url": "https://jenkins-host",
      "username": "neo",
      "password": "************",
      "isPlugin": false,
      "config": {
      },
      "status": "ok",
      "statusDate": "2021-04-20T02:42:43Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 2157,
      "name": "Labs Microsoft DNS",
      "enabled": true,
      "type": "microsoft.dns",
      "integrationType": {
        "id": 8,
        "code": "microsoft.dns",
        "name": "Microsoft DNS"
      },
      "url": "10.0.0.53",
      "username": "administrator",
      "password": "************",
      "serviceFlag": true,
      "isPlugin": false,
      "config": {
      },
      "status": "ok",
      "statusDate": "2021-04-11T00:06:56Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 3107,
      "name": "Labs phpIPAM",
      "enabled": true,
      "type": "phpipam",
      "integrationType": {
        "id": 20,
        "code": "phpipam",
        "name": "phpIPAM"
      },
      "url": "http://10.0.0.168/api/",
      "port": "22",
      "username": "Admin",
      "password": "************",
      "isPlugin": false,
      "config": {
        "appId": "neodev"
      },
      "status": "ok",
      "statusDate": "2021-04-24T03:00:05Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 146,
      "name": "Labs PowerDNS",
      "enabled": true,
      "type": "powerDns",
      "integrationType": {
        "id": 11,
        "code": "powerDns",
        "name": "PowerDNS"
      },
      "url": "https://powerdns-host",
      "password": "************",
      "version": "4",
      "isPlugin": false,
      "config": {
      },
      "status": "ok",
      "statusDate": "2021-04-24T03:47:15Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 7298,
      "name": "Labs Puppet",
      "enabled": true,
      "type": "puppet",
      "integrationType": {
        "id": 2,
        "code": "puppet",
        "name": "Puppet"
      },
      "isPlugin": false,
      "config": {
        "cm": {
          "puppetMaster": "puppet-host",
          "puppetFireNow": "true",
          "puppetSshUser": "neo",
          "puppetSshPassword": "************"
        }
      },
      "status": "ok",
      "statusDate": null,
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 4,
      "name": "Labs Chef",
      "enabled": true,
      "type": "chef",
      "integrationType": {
        "id": 1,
        "code": "chef",
        "name": "Chef"
      },
      "url": "https://chef-host",
      "username": "neo",
      "isPlugin": false,
      "config": {
        "cm": {
          "endpoint": "https://chef.bertramlabs.com",
          "org": "my-org",
          "chefUser": "neo",
          "userKey": "-----BEGIN RSA PRIVATE KEY-----\r\n...RSA PRIVATE KEY-----",
          "version": "14.13.11",
          "chefUseFqdn": null,
          "windowsVersion": "14.13.11",
          "windowsInstallUrl": ""
        },
        "databags": [
          {
            "path": "/etc/chef/databag_secret",
            "key": "************"
          }
        ]
      },
      "status": "ok",
      "statusDate": null,
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 4369,
      "name": "Labs Remedy",
      "enabled": true,
      "type": "remedy",
      "integrationType": {
        "id": 27,
        "code": "remedy",
        "name": "Remedy"
      },
      "url": "http://remedy-host",
      "username": "neo",
      "password": "************",
      "isPlugin": false,
      "config": {
        "approvalUser": "Thomas Anderson",
        "company": "Metacorp",
        "remedyIgnoreSSLErrors": null
      },
      "status": "ok",
      "statusDate": "2021-04-15T02:42:33Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 3662,
      "name": "Labs ServiceNow",
      "enabled": true,
      "type": "serviceNow",
      "integrationType": {
        "id": 10,
        "code": "serviceNow",
        "name": "ServiceNow"
      },
      "url": "https://my-sevicenow-server/",
      "username": "automation",
      "password": "************",
      "isPlugin": false,
      "config": {
        "incidentAccess": true,
        "requestAccess": true,
        "serviceNowCMDBBusinessObject": "",
        "serviceNowCustomCmdbMapping": "",
        "serviceNowCmdbClassMapping": [
          {
            "id": "44",
            "code": "amazonLinux",
            "name": "Amazon Docker Host",
            "nowClass": "cmdb_ci_ec2_instance"
          },
          {
            "id": "46",
            "code": "amazonUnmanaged",
            "name": "Amazon Instance",
            "nowClass": "cmdb_ci_ec2_instance"
          },
          {
            "id": "47",
            "code": "amazonVm",
            "name": "Amazon Instance",
            "nowClass": "cmdb_ci_ec2_instance"
          },
          {
            "id": "49",
            "code": "amazonWindowsVm",
            "name": "Amazon Windows Instance",
            "nowClass": "cmdb_ci_ec2_instance"
          },
          {
            "id": "45",
            "code": "amazonWindows",
            "name": "Amazon Windows Node",
            "nowClass": "cmdb_ci_ec2_instance"
          },
          {
            "id": "13",
            "code": "hypervHypervisor",
            "name": "Hyper-V Hypervisor",
            "nowClass": "cmdb_ci_hyper_v_server"
          },
          {
            "id": "16",
            "code": "hypervVm",
            "name": "Hyper-V Linux VM",
            "nowClass": "cmdb_ci_hyper_v_instance"
          },
          {
            "id": "14",
            "code": "hypervWindows",
            "name": "Hyper-V Windows Host",
            "nowClass": "cmdb_ci_hyper_v_instance"
          },
          {
            "id": "17",
            "code": "hypervWindowsVm",
            "name": "Hyper-V Windows VM",
            "nowClass": "cmdb_ci_hyper_v_instance"
          },
          {
            "id": "75",
            "code": "vmwareVm",
            "name": "VMware Linux VM",
            "nowClass": "cmdb_ci_vmware_instance"
          },
          {
            "id": "73",
            "code": "vmwareWindows",
            "name": "VMware Windows Node",
            "nowClass": "cmdb_ci_vmware_instance"
          },
          {
            "id": "76",
            "code": "vmwareWindowsVm",
            "name": "VMware Windows VM",
            "nowClass": "cmdb_ci_vmware_instance"
          },
          {
            "id": "74",
            "code": "vmwareUnmanaged",
            "name": "Vmware VM",
            "nowClass": "cmdb_ci_vmware_instance"
          }
        ]
      },
      "status": "ok",
      "statusDate": "2021-03-18T01:14:19Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 5999,
      "name": "Labs SolarWinds",
      "enabled": true,
      "type": "solarwindsipam",
      "integrationType": {
        "id": 28,
        "code": "solarwindsipam",
        "name": "SolarWinds IPAM"
      },
      "url": "https://10.0.0.13:17778",
      "port": "22",
      "username": "admin",
      "password": "************",
      "isPlugin": false,
      "config": {
        "_inventoryExisting": ""
      },
      "status": "syncing",
      "statusDate": "2021-04-24T03:00:04Z",
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    },
    {
      "id": 9470,
      "name": "Labs Venafi",
      "enabled": true,
      "type": "venafi",
      "integrationType": {
        "id": 19,
        "code": "venafi",
        "name": "Venafi"
      },
      "host": "https://venafi-url",
      "username": "tppadmin",
      "password": "************",
      "serviceMode": "static",
      "isPlugin": false,
      "config": {
      },
      "status": "ok",
      "statusDate": null,
      "statusMessage": null,
      "lastSync": null,
      "nextRunDate": null,
      "lastSyncDuration": null
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 25,
    "total": 34
  }
}

This endpoint retrieves a list of integrations.

HTTP Request

GET $serverUrl/api/integrations

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort id Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
id Filter by id
name Filter by integration Name
type Filter by integration Type Code
url Filter by integration Service URL
host Filter by integration Host
port Filter by integration Port
username Filter by integration Username
version Filter by integration Version
windowsVersion Filter by integration Windows Version
status Filter by integration status
objects false Include objects=true to return the Integration Objects for each integration. Available in api version 5.2.8/5.3.2.

Get a Specific Integration

curl "$serverUrl/api/integrations/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "integration": {
    "id": 63,
    "name": "GitTest",
    "enabled": true,
    "type": "git",
    "integrationType": {
      "id": 6,
      "code": "git",
      "name": "Git repository"
    },
    "url": "https://github.com/organization/repo.git",
    "username": "neo",
    "password": "",
    "token": "************",
    "serviceKey": {
      "id": 15,
      "name": "git_key"
    },
    "serviceMode": "static",
    "isPlugin": false,
    "config": {
      "defaultBranch": "mybranch",
      "cacheEnabled": true
    },
    "status": "ok",
    "statusDate": null,
    "statusMessage": null,
    "lastSync": null,
    "nextRunDate": null,
    "lastSyncDuration": null
  }
}

This endpoint retrieves a specific Integration.

HTTP Request

GET $serverUrl/api/integrations/:id

URL Parameters

Parameter Description
id ID of the Integration

Query Parameters

Parameter Default Description
objects false Include objects=true to return the Integration Objects for the integration. Available in api version 5.2.8/5.3.2.

Create an Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Jenkins",
    "enabled": true,
    "type": "jenkins",
    "url": "https://jenkins.dev.morpheusdata.com",
    "username": "my-user",
    "password": "my-password"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This endpoint creates a new Integration.

HTTP Request

POST $serverUrl/api/integrations

Create Integration Parameters

Parameter Required Default Description
name Y Name, a unique identifier for the integration
type Y Integration Type code
enabled N true Enabled

These are the common parameters for all types of integrations. They are passed under an object called integration. Each integration type may support additional parameters which can be determined by the Integration Type Option Types endpoint. See examples below, such as Jenkins, ServiceNow, and Github.

Update an Integration

curl -XPUT "$serverUrl/api/integrations/:id" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Legacy Jenkins",
    "enabled": "true,
    "url": "https://oldjenkins.dev.morpheusdata.com",
    "username": "new-user",
    "password": "new-password"
  }
}'

The above command returns JSON structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This endpoint updates an existing Integration. For some types, update triggers a refresh to be performed. Refresh can be avoided by passing refresh=false.

HTTP Request

PUT $serverUrl/api/integrations/:id

URL Parameters

Parameter Description
id The ID of the Integration

Update Integration Parameters

Parameter Required Default Description
name N Name, a unique identifier for the integration
enabled N Enabled
refresh N true Pass false to skip refresh. By default, refresh is done on update, when it is supported by the integration type.

These are the common parameters for all types of integrations. They are passed under an object called integration. Each integration type may support additional parameters which can be determined by the Integration Type Option Types endpoint. See examples below, such as Jenkins, ServiceNow, and Github.

Refresh an Integration

curl -XPOST "$serverUrl/api/integrations/:id/refresh" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{}'

The above command returns JSON structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This endpoint will refresh an existing Integration. Only some types support this and will actually perform an action as a result.

HTTP Request

POST $serverUrl/api/integrations/:id/refresh

URL Parameters

Parameter Description
id The ID of the Integration

Delete an Integration

curl -XDELETE "$serverUrl/api/integrations/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint deletes an existing integration.

HTTP Request

DELETE $serverUrl/api/integrations/:id

URL Parameters

Parameter Description
id The ID of the Integration

Ansible Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Ansible",
    "type": "ansible",
    "serviceUrl": "https://ansible-url",
    "serviceUsername": "ansible-user",
    "servicePassword": "************",
    "config": {
      "ansibleDefaultBranch": "main",
      "ansiblePlaybooks": "/",
      "ansibleRoles": "/roles",
      "ansibleGroupVars": "/vars",
      "ansibleHostVars": "/hosts",
      "ansibleGalaxyEnabled": false,
      "ansibleVerbose": true,
      "ansibleCommandBus": true
    }
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Ansible integration

HTTP Request

POST $serverUrl/api/integrations

Ansible Integration Parameters

Parameter Required Default Description
serviceUrl Y Ansible Git URL
serviceUsername N Git Options: User
servicePassword N Git Options: Password
serviceToken N Git Options: Access Token
serviceKey N Git Options: Key Pair ID
config.defaultBranch N main / master Default Branch
config.ansiblePlaybooks N Playbooks Path
config.ansibleRoles N Roles Path
config.ansibleGroupVars N Group Variables Path
config.ansibleHostVars N Host Variables Path
config.ansibleGalaxyEnabled N Use Ansible Galaxy
config.ansibleVerbose N Use Verbose Logging
config.ansibleCommandBus N Use Morpheus Agent Command Bus
config.cacheEnabled N Enable Git Repository Caching

ServiceNow Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data ServiceNow",
    "type": "serviceNow",
    "url": "https://my-sevicenow-server/",
    "username": "automation",
    "password": "************",
    "config": {
      "incidentAccess": true,
      "requestAccess": true,
      "serviceNowCMDBBusinessObject": "",
      "serviceNowCustomCmdbMapping": "",
      "serviceNowCmdbClassMapping": [
        {
          "id": "44",
          "code": "amazonLinux",
          "name": "Amazon Docker Host",
          "nowClass": "cmdb_ci_ec2_instance"
        },
        {
          "id": "46",
          "code": "amazonUnmanaged",
          "name": "Amazon Instance",
          "nowClass": "cmdb_ci_ec2_instance"
        },
        {
          "id": "47",
          "code": "amazonVm",
          "name": "Amazon Instance",
          "nowClass": "cmdb_ci_ec2_instance"
        },
        {
          "id": "49",
          "code": "amazonWindowsVm",
          "name": "Amazon Windows Instance",
          "nowClass": "cmdb_ci_ec2_instance"
        },
        {
          "id": "45",
          "code": "amazonWindows",
          "name": "Amazon Windows Node",
          "nowClass": "cmdb_ci_ec2_instance"
        },
        {
          "id": "13",
          "code": "hypervHypervisor",
          "name": "Hyper-V Hypervisor",
          "nowClass": "cmdb_ci_hyper_v_server"
        },
        {
          "id": "16",
          "code": "hypervVm",
          "name": "Hyper-V Linux VM",
          "nowClass": "cmdb_ci_hyper_v_instance"
        },
        {
          "id": "14",
          "code": "hypervWindows",
          "name": "Hyper-V Windows Host",
          "nowClass": "cmdb_ci_hyper_v_instance"
        },
        {
          "id": "17",
          "code": "hypervWindowsVm",
          "name": "Hyper-V Windows VM",
          "nowClass": "cmdb_ci_hyper_v_instance"
        },
        {
          "id": "75",
          "code": "vmwareVm",
          "name": "VMware Linux VM",
          "nowClass": "cmdb_ci_vmware_instance"
        },
        {
          "id": "73",
          "code": "vmwareWindows",
          "name": "VMware Windows Node",
          "nowClass": "cmdb_ci_vmware_instance"
        },
        {
          "id": "76",
          "code": "vmwareWindowsVm",
          "name": "VMware Windows VM",
          "nowClass": "cmdb_ci_vmware_instance"
        },
        {
          "id": "74",
          "code": "vmwareUnmanaged",
          "name": "Vmware VM",
          "nowClass": "cmdb_ci_vmware_instance"
        }
      ]
    }
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This example creates a new ServiceNow integration. See Integration Objects for configuring an Exposed Catalog Item.

HTTP Request

POST $serverUrl/api/integrations

ServiceNow Integration Parameters

Parameter Required Default Description
serviceUrl Y ServiceNow Host
serviceUsername Y User
servicePassword Y Password
config.serviceNowCustomCmdbMapping N CMDB Custom Mapping
config.serviceNowCmdbClassMapping N CMDB Class Mapping
config.serviceNowCMDBBusinessObject N CMDB Business Object

List ServiceNow Integration Objects

curl "$serverUrl/api/integrations/:integration_id/objects" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "objects": [
    {
      "id": 4,
      "name": "Dev Apache",
      "type": "catalog",
      "refType": "CatalogItemType",
      "refId": 27,
      "catalogItemType": {
        "id": 27,
        "name": "Dev Apache"
      }
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 4,
    "total": 4
  }
}

This endpoint retrieves a list of exposed objects for a specific integration.

HTTP Request

GET $serverUrl/api/integrations/:integration_id/objects

URL Parameters

Parameter Description
integration_id ID of the Integration

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use 'desc’ to reverse sort
phrase Filter by wildcard search of name
id Filter by id
name Filter by name
type Filter by type: catalog
refId Filter by refId

Get a Specific ServiceNow Integration Object

curl "$serverUrl/api/integrations/:integration_id/objects/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "object": {
    "id": 4,
    "name": "Dev Apache",
    "type": "catalog",
    "refType": "CatalogItemType",
    "refId": 27,
    "catalogItemType": {
      "id": 27,
      "name": "Dev Apache"
    }
  }
}

This endpoint retrieves a specific integration object.

HTTP Request

GET $serverUrl/api/integrations/:integration_id/objects/:id

URL Parameters

Parameter Description
integration_id ID of the Integration
id ID of the Integration Object

Create a ServiceNow Exposed Catalog Item

curl -XPOST "$serverUrl/api/integrations/:integration_id/objects" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "type": "catalog",
    "catalogItemType": 27
  }
}'

The above command returns JSON structured like this:

{
  "success": true,
  "object": {
    "id": 4
  }
}

This endpoint creates an Exposed Catalog Item. This is an integration object of type catalog that references a Catalog Item Type.

HTTP Request

POST $serverUrl/api/integrations/:integration_id/objects

URL Parameters

Parameter Description
integration_id ID of the Integration

Exposed Catalog Item Parameters

The parameters for creating an integration object are passed under an object named object.

Parameter Required Default Description
name N (catalog item name) Name to display
type Y Integration Object Type code: catalog
catalogItemType Y Catalog Item Type ID

Delete an Integration Object

curl -XDELETE "$serverUrl/api/integrations/:integration_id/objects/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

This endpoint deletes an existing integration object.

HTTP Request

DELETE $serverUrl/api/integrations/:integration_id/objects/:id

URL Parameters

Parameter Description
integration_id ID of the Integration
id The ID of the Integration Object

Salt Master Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Salt Master",
    "type": "saltMaster",
    "serviceUrl": "salt-host",
    "serviceUsername": "salt-username",
    "servicePassword": "salt-password",
    "servicePort": "22"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Salt Master integration

HTTP Request

POST $serverUrl/api/integrations

Salt Master Integration Parameters

Parameter Required Default Description
serviceMode N single Topology
serviceUrl Y Salt Master
secondary N Salt Syndic
servicePort N 22 SSH Port
serviceUsername Y User
servicePassword N Password
serviceKey N Master Key Pair
authKey N Signing Key
servicePath N Working Directory
serviceVersion N Salt Version
serviceWindowsVersion N Salt Version (Windows)
repoUrl N Repo URL
serviceConfig N Minion Config
config.saltApplyOnMinion N Apply State via Minion instead of Master (salt-call)
serviceCommand N Post Provision Commands

Docker Repository Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Docker Repository",
    "type": "docker.registry",
    "serviceUrl": "https://index.docker.io/v1/",
    "serviceUsername": "admin",
    "servicePassword": "************"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Docker Repository integration

HTTP Request

POST $serverUrl/api/integrations

Docker Repository Integration Parameters

Parameter Required Default Description
serviceUrl Y Repository URL
serviceUsername Y User
servicePassword Y Password

Git Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Git",
    "type": "git",
    "serviceUrl": "https://git-url",
    "serviceUsername": "git-user",
    "servicePassword": "************",
    "config": {
      "defaultBranch": "main"
    }
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Git integration

HTTP Request

POST $serverUrl/api/integrations

Git Integration Parameters

Parameter Required Default Description
serviceUrl Y Git URL
serviceUsername Y User
servicePassword N Password
serviceToken N Access Token
serviceKey N Key Pair ID
config.defaultBranch N main / master Default Branch
config.cacheEnabled N Enable Git Repository Caching

Github Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Github",
    "type": "github",
    "serviceUsername": "github-user",
    "servicePassword": "************"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Github integration

HTTP Request

POST $serverUrl/api/integrations

Github Integration Parameters

Parameter Required Default Description
serviceUsername Y User
servicePassword N Password
serviceToken N Access Token
serviceKey N Key Pair ID
config.cacheEnabled N Enable Git Repository Caching

Jenkins Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Jenkins",
    "type": "jenkins",
    "serviceUrl": "https://jenkins-url",
    "serviceUsername": "jenkins-user",
    "servicePassword": "************"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Jenkins integration

HTTP Request

POST $serverUrl/api/integrations

Jenkins Integration Parameters

Parameter Required Default Description
serviceUrl Y Jenkins Url
serviceUsername Y User
servicePassword N Password

Venafi Integration

curl -XPOST "$serverUrl/api/integrations" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "integration": {
    "name": "Morpheus Data Venafi",
    "type": "venafi",
    "serviceHost": "https://venafi-url",
    "serviceUsername": "venafi-user",
    "servicePassword": "************"
  }
}'

The above command returns JSON Structured like this:

{
  "success": true,
  "integration": {
    "id": 1
  }
}

This is an example of create for a new Venafi integration.

HTTP Request

POST $serverUrl/api/integrations

Venafi Integration Parameters

Parameter Required Default Description
serviceHost Y Venafi Host
serviceUsername Y User
servicePassword N Password

Integration Types

A Integration Type is specific third party software that the appliance can be configured to integrate with, such as Chef, Git, Jenkins, etc.

curl "$serverUrl/api/integration-types"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "integrationTypes": [
    {
      "id": 19,
      "code": "aci",
      "name": "ACI",
      "description": null,
      "category": "network",
      "enabled": true,
      "creatable": false,
      "hasCMDB": false,
      "hasCMDBDiscovery": false,
      "hasCM": false,
      "hasDNS": null,
      "hasApprovals": false,
      "isPlugin": null
    },
    {
      "id": 3,
      "code": "ansible",
      "name": "Ansible",
      "description": null,
      "category": "automation",
      "enabled": true,
      "creatable": true,
      "hasCMDB": false,
      "hasCMDBDiscovery": false,
      "hasCM": false,
      "hasDNS": null,
      "hasApprovals": false,
      "isPlugin": null
    }
  ],
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 25,
    "total": 25
  }
}

HTTP Request

GET $serverUrl/api/integration-types

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
optionTypes false Pass true to include optionTypes in the response for each integration type.
phrase Filter by wildcard search of name and code
name Filter by name
code Filter by code
description Filter by description
category Filter by category
creatable Filter by creatable
enabled Filter by enabled
hasCMDB Filter by hasCMDB
hasCMDBDiscovery Filter by hasCMDBDiscovery
hasCM Filter by hasCM
hasDNS Filter by hasDNS
hasApprovals Filter by hasApprovals
isPlugin Filter by isPlugin

Get a Specific Integration Type

curl "$serverUrl/api/integration-types/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "integrationType": {
    "id": 16,
    "code": "github",
    "name": "GitHub",
    "description": null,
    "category": "code",
    "enabled": true,
    "creatable": true,
    "hasCMDB": false,
    "hasCMDBDiscovery": false,
    "hasCM": false,
    "hasDNS": null,
    "hasApprovals": false,
    "isPlugin": null
  }
}

This endpoint will retrieve a specific integration type by id.

HTTP Request

GET $serverUrl/api/integration-types/:id

URL Parameters

Parameter Description
ID The ID of the integration type

Query Parameters

Parameter Default Description
optionTypes false Pass true to include optionTypes in the response.

Get Integration Type Option Types

curl "$serverUrl/api/integration-types/10/option-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "optionTypes": [
    {
      "id": 434,
      "name": "serviceUrl",
      "description": null,
      "code": "accountIntegration.serviceNow.serviceNowUrl",
      "fieldName": "serviceUrl",
      "fieldLabel": "ServiceNow Host",
      "fieldCode": "gomorpheus.optiontype.ServicenowHost",
      "fieldContext": "integration",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "fieldInput": null,
      "placeHolder": null,
      "verifyPattern": null,
      "helpBlock": "",
      "helpBlockFieldCode": null,
      "defaultValue": null,
      "optionSource": null,
      "optionList": null,
      "type": "text",
      "advanced": false,
      "required": true,
      "exportMeta": null,
      "editable": true,
      "creatable": true,
      "config": {
      },
      "displayOrder": 0,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": null,
      "dependsOnCode": null,
      "visibleOnCode": null,
      "requireOnCode": null,
      "contextualDefault": null,
      "displayValueOnDetails": null
    },
    {
      "id": 435,
      "name": "serviceUsername",
      "description": null,
      "code": "accountIntegration.serviceNow.serviceNowUser",
      "fieldName": "serviceUsername",
      "fieldLabel": "User",
      "fieldCode": "gomorpheus.optiontype.User",
      "fieldContext": "integration",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "fieldInput": null,
      "placeHolder": null,
      "verifyPattern": null,
      "helpBlock": "",
      "helpBlockFieldCode": null,
      "defaultValue": null,
      "optionSource": null,
      "optionList": null,
      "type": "text",
      "advanced": false,
      "required": true,
      "exportMeta": null,
      "editable": true,
      "creatable": true,
      "config": {
      },
      "displayOrder": 1,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": null,
      "dependsOnCode": null,
      "visibleOnCode": null,
      "requireOnCode": null,
      "contextualDefault": null,
      "displayValueOnDetails": null
    },
    {
      "id": 436,
      "name": "servicePassword",
      "description": null,
      "code": "accountIntegration.serviceNow.serviceNowPassword",
      "fieldName": "servicePassword",
      "fieldLabel": "Password",
      "fieldCode": "gomorpheus.optiontype.Password",
      "fieldContext": "integration",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "fieldInput": null,
      "placeHolder": null,
      "verifyPattern": null,
      "helpBlock": "",
      "helpBlockFieldCode": null,
      "defaultValue": null,
      "optionSource": null,
      "optionList": null,
      "type": "password",
      "advanced": false,
      "required": true,
      "exportMeta": null,
      "editable": true,
      "creatable": true,
      "config": {
      },
      "displayOrder": 2,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": null,
      "dependsOnCode": null,
      "visibleOnCode": null,
      "requireOnCode": null,
      "contextualDefault": null,
      "displayValueOnDetails": null
    },
    {
      "id": 1128,
      "name": "serviceNowCustomCmdbMapping",
      "description": null,
      "code": "accountIntegration.serviceNow.serviceNowCustomCmdbMapping",
      "fieldName": "serviceNowCustomCmdbMapping",
      "fieldLabel": "CMDB Custom Mapping",
      "fieldCode": "gomorpheus.optiontype.CmdbCustomMapping",
      "fieldContext": "config",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "fieldInput": null,
      "placeHolder": null,
      "verifyPattern": null,
      "helpBlock": "",
      "helpBlockFieldCode": null,
      "defaultValue": null,
      "optionSource": null,
      "optionList": null,
      "type": "code-editor",
      "advanced": false,
      "required": false,
      "exportMeta": false,
      "editable": true,
      "creatable": true,
      "config": {
      },
      "displayOrder": 7,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": false,
      "dependsOnCode": null,
      "visibleOnCode": null,
      "requireOnCode": null,
      "contextualDefault": false,
      "displayValueOnDetails": null
    },
    {
      "id": 1734,
      "name": "serviceNowCmdbClassMapping",
      "description": null,
      "code": "accountIntegration.serviceNow.serviceNowCmdbClassMapping",
      "fieldName": "serviceNowCmdbClassMapping.id",
      "fieldLabel": "CMDB Class Mapping",
      "fieldCode": "gomorpheus.optiontype.CmdbClassMapping",
      "fieldContext": "config",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "fieldInput": "nowClass",
      "placeHolder": null,
      "verifyPattern": null,
      "helpBlock": "Define the mapping between Morpheus server types and ServiceNow CI classes",
      "helpBlockFieldCode": null,
      "defaultValue": null,
      "optionSource": "serviceNowServerMappings",
      "optionList": null,
      "type": "multiSelect",
      "advanced": false,
      "required": false,
      "exportMeta": false,
      "editable": true,
      "creatable": true,
      "config": {
        "addOnSelect": true
      },
      "displayOrder": 8,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": false,
      "dependsOnCode": null,
      "visibleOnCode": null,
      "requireOnCode": null,
      "contextualDefault": false,
      "displayValueOnDetails": false
    },
    {
      "id": 1129,
      "name": "CMDB Business Object",
      "description": null,
      "code": "accountIntegration.serviceNow.serviceNowCMDBBusinessObject",
      "fieldName": "serviceNowCMDBBusinessObject",
      "fieldLabel": "CMDB Business Object",
      "fieldCode": "gomorpheus.optiontype.CmdbBusinessObject",
      "fieldContext": "config",
      "fieldGroup": null,
      "fieldClass": null,
      "fieldAddOn": null,
      "fieldComponent": null,
      "fieldInput": null,
      "placeHolder": null,
      "verifyPattern": null,
      "helpBlock": "Specify a default CI class to use when creating the CMDB record.  By default, Configuration - Base Items - All (cmdb_ci_vm_instance) is used.",
      "helpBlockFieldCode": null,
      "defaultValue": null,
      "optionSource": null,
      "optionList": null,
      "type": "text",
      "advanced": false,
      "required": false,
      "exportMeta": false,
      "editable": true,
      "creatable": true,
      "config": {
      },
      "displayOrder": 10,
      "wrapperClass": null,
      "enabled": true,
      "noBlank": false,
      "dependsOnCode": null,
      "visibleOnCode": null,
      "requireOnCode": null,
      "contextualDefault": false,
      "displayValueOnDetails": null
    }
  ]
}

This endpoint will retrieve the list of option types for a specific integration type.

HTTP Request

GET $serverUrl/api/integration-types/:id/option-types

URL Parameters

Parameter Description
ID The ID of the integration type

Policies

Provides API interfaces for managing Policies.

Get All Policies

curl "$serverUrl/api/policies"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "policies": [
    {
      "id": 1,
      "name": null,
      "description": "global max containers",
      "policyType": {
        "id": 5,
        "code": "maxContainers",
        "name": "Max Containers"
      },
      "zone": null,
      "site": null,
      "user": null,
      "refType": null,
      "refId": null,
      "config": {
        "maxContainers": 999
      },
      "enabled": true,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "accounts": [

      ]
    },
    {
      "id": 2,
      "name": null,
      "description": "dev budget",
      "policyType": {
        "id": 16,
        "code": "maxPrice",
        "name": "Budget"
      },
      "zone": null,
      "site": null,
      "user": null,
      "refType": null,
      "refId": null,
      "config": {
        "maxPrice": 1500,
        "maxPriceCurrency": "USD",
        "maxPriceUnit": "month"
      },
      "enabled": true,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "accounts": [
        {
          "id": 2,
          "name": "dev"
        }
      ]
    },
    {
      "id": 3,
      "name": "test group maxcores",
      "description": null,
      "policyType": {
        "id": 3,
        "code": "maxCores",
        "name": "Max Cores"
      },
      "zone": null,
      "site": {
        "id": 2,
        "name": "test group"
      },
      "user": null,
      "refType": "ComputeSite",
      "refId": 1,
      "config": {
        "maxCores": 20
      },
      "enabled": true,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "accounts": [

      ]
    },
    {
      "id": 4,
      "name": null,
      "description": "hulk max storage",
      "policyType": {
        "id": 2,
        "code": "maxStorage",
        "name": "Max Storage"
      },
      "zone": null,
      "site": null,
      "user": {
        "id": 26,
        "username": "hulk"
      },
      "refType": "User",
      "refId": 26,
      "config": {
        "maxStorage": 10000
      },
      "enabled": true,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "accounts": [

      ]
    }
  ],
  "meta": {
    "size": 4,
    "total": 4,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all policies associated with the account.

HTTP Request

GET $serverUrl/api/policies

Query Parameters

Parameter Default Description
name If specified will return an exact match on name
phrase If specified will return a partial match on name

Get a Specific Policy

curl "$serverUrl/api/policies/4" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "policy": {
    "id": 4,
    "name": "hulk max storage",
    "description": "Limit the hulkster",
    "policyType": {
      "id": 2,
      "code": "maxStorage",
      "name": "Max Storage"
    },
    "zone": null,
    "site": null,
    "user": {
      "id": 26,
      "username": "hulk"
    },
    "refType": "User",
    "refId": 26,
    "config": {
      "maxStorage": "10000"
    },
    "enabled": true,
    "owner": {
      "id": 1,
      "name": "root"
    },
    "accounts": [
    ]
  }
}

This endpoint retrieves a specific policy.

HTTP Request

GET $serverUrl/api/policies/:id

URL Parameters

Parameter Description
ID The ID of the policy to retrieve

Policy Types

curl "$serverUrl/api/policy-types" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "policyTypes": [
    {
      "id": 15,
      "code": "createBackup",
      "name": "Backup Creation",
      "description": "",
      "category": "provision",
      "loadMethod": "loadBackupCreation",
      "enforceMethod": "enforceBackupCreation",
      "prepareMethod": "prepareBackupCreation",
      "validateMethod": "validateBackupCreation",
      "enforceOnProvision": true,
      "enforceOnManaged": false,
      "optionTypes": [
        {
          "code": "policyType.createBackupType",
          "name": "Enforcement Type",
          "description": null,
          "type": "select",
          "displayOrder": 1,
          "optionSource": "policyGenericType",
          "defaultValue": "",
          "placeHolder": null,
          "helpBlock": "",
          "required": true,
          "fieldLabel": "Enforcement Type",
          "fieldName": "createBackupType",
          "fieldContext": "config"
        },
        {
          "code": "policyType.createBackup",
          "name": "Create Backup",
          "description": null,
          "type": "checkbox",
          "displayOrder": 2,
          "optionSource": null,
          "defaultValue": "",
          "placeHolder": null,
          "helpBlock": "",
          "required": true,
          "fieldLabel": "Create Backup",
          "fieldName": "createBackup",
          "fieldContext": "config"
        }
      ]
    }
  ],
  "meta": {
    "size": 16,
    "total": 16,
    "offset": 0,
    "max": 1000
  }
}

This endpoint returns a list of all policy types.

HTTP Request

GET $serverUrl/api/policy-types

Policy Type Options

Backup Creation (createBackup)
Parameter Default Description
config.createBackupType Enforcement Type - [user, fixed]
config.createBackup false Create Backup [true, false]
Budget (maxPrice)
Parameter Default Description
config.maxPrice Max Price: Maximum total price for all instances
config.maxPriceCurrency USD Currency code
config.maxPriceUnit month Unit of time [month, hour]
Expiration (lifecycle)
Parameter Default Description
config.lifecycleType user Expiration Type - [user, fixed]
config.lifecycleAge 30 Expiration Days - Configures the number of days the instance is allowed to exist before being removed.
config.lifecycleRenewal 7 Renewal Days - If the instance is renewed, this is the number of day increments the expiration date is increased by.
config.lifecycleNotify 1 Notification Days - This allows an email notice to be sent out x days before the instance is going to expire.
config.lifecycleMessage Instance ${instance?.name} is set to expire on ${instance?.expireDate} Notification Message
config.lifecycleAutoRenew on Allow Auto Extensions
config.lifecycleExtensionsBeforeApproval 0 Configures the number of extensions allowed before approval is required.
config.accountIntegrationId Approval Integration ID
config.lifecycleWorkflowId Approval Workflow ID
Host Name (serverNaming)
Parameter Default Description
config.serverNamingType Naming Type - [user, fixed]
config.serverNamingPattern Name pattern - uses ${variable} string interpolation. Available variables are:
groupName, groupCode, cloudName, cloudCode, type, accountId, account, accountType, platform, username, userId, userInitials, provisionType
config.serverNamingConflict false Resolve Conflicts
Hostname (hostNaming)
Parameter Default Description
config.hostNamingType Naming Type - [user, fixed]
config.hostNamingPattern Name Pattern - uses ${variable} string interpolation. Available variables are:
groupName, groupCode, cloudName, cloudCode, type, accountId, account, accountType, platform, username, userId, userInitials, provisionType
Instance Name(naming)
Parameter Default Description
config.namingType Naming Type - [user, fixed]
config.namingPattern Name pattern - uses ${variable} string interpolation. Available variables are:
groupName, groupCode, cloudName, cloudCode, type, accountId, account, accountType, platform, username, userId, userInitials, provisionType
config.namingConflict false Resolve Conflicts
Max Containers (maxContainers)
Parameter Default Description
config.maxContainers The max number of containers
Max Cores (maxCores)
Parameter Default Description
config.maxCores The max number of cores
Max Hosts (maxHosts)
Parameter Default Description
config.maxHosts The max number of hosts
Max Memory (maxMemory)
Parameter Default Description
config.maxMemory The max number of memory (GB)
Max Storage (maxStorage)
Parameter Default Description
config.maxStorage The max number of memory (GB)
Max VMs (maxVms)
Parameter Default Description
config.maxVms The max number of virtual machines
Power Schedule (powerSchedule)
Parameter Default Description
config.powerScheduleType Enforcement Type - [user, fixed]
config.powerSchedule Power Schedule ID
Provision Approval (provisionApproval)
Parameter Default Description
config.accountIntegrationId Account Integration ID
config.workflowId Workflow ID
Shutdown (shutdown)
Parameter Default Description
config.shutdownType user Shutdown Type - [user, fixed]
config.shutdownAge 30 Shutdown Days - Configures the number of days the instance is allowed to exist before being removed.
config.shutdownRenewal 7 Renewal Days - If the instance is renewed, this is the number of day increments the expiration date is increased by.
config.shutdownNotify 1 Notification Days - This allows an email notice to be sent out x days before the instance is going to expire.
config.shutdownMessage Instance ${instance?.name} is set to shutdown on ${instance?.shutdownDate} Notification Message
config.shutdownAutoRenew on Allow Auto Extensions
config.shutdownExtensionsBeforeApproval 0 Configures the number of extensions allowed before approval is required.
config.accountIntegrationId Approval Integration ID
config.lifecycleWorkflowId Approval Workflow ID
User Creation (createUser)
Parameter Default Description
config.createUserType Enforcement Type - [user, fixed]
config.createUser false Create User [true, false]

Create a Policy

curl -XPOST "$serverUrl/api/policies" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "policy": {
    "name": "max hosts",
    "description": null,
    "policyType": {
      "code": "maxHosts"
    },
    "config": {
      "maxHosts": 99
    },
    "enabled": true,
    "accounts": []
  }
}'

The above command returns JSON structured like getting a single policy:

HTTP Request

POST $serverUrl/api/policies

JSON Parameters

Parameter Default Description
name A name for the policy
description A description for the policy
policyType.code The policy type. [maxMemory, maxStorage, maxCores, maxContainers, etc.]
config A map of config values. The expected values vary by policyType. See Policy Types.
enabled true Enabled. Set to false to disable.
refType Scope object type. [ComputeSite, ComputeZone, User, Role]
refId Scope object ID, of group, cloud, user, etc.
accounts Array of tenants to scope the policy to.
eachUser false Apply individually to each user in role, Only for policies scoped to a Role

Create a Policy For a Group

Policies can be scoped to a group by passing the following:

Parameter Value
refType ComputeSite
refId The ID of the group

Alternatively, the Group Policies endpoint can be used.

Create a Policy For a Cloud

Policies can be scoped to a cloud by passing the following:

Parameter Value
refType ComputeZone
refId The ID of the cloud

Alternatively, the Cloud Policies endpoint can be used.

Create a Policy For a User

Policies can be scoped to a user by passing the following:

Parameter Value
refType User
refId The ID of the user

Create a Policy For a Role

Policies can be scoped to a role by passing the following:

Parameter Value
refType Role
refId The ID of the role

Update a Policy

curl -XPUT "$serverUrl/api/policies/1" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "policy": {
    "name": "max containers 1000",
    "config": {
      "maxContainers": 1000
    },
  }
}'

The above command returns JSON structured like getting a single policy:

HTTP Request

PUT $serverUrl/api/policies/1

URL Parameters

Parameter Description
ID The ID of the policy

JSON Parameters

Parameter Default Description
name A name for the policy
description A description for the policy
config A map of config values. The expected values vary by policyType.
enabled true Enabled. Set to false to disable.
accounts Array of tenants to scope the policy to.

Delete a Policy

curl -XDELETE "$serverUrl/api/policies/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

Will delete a policy from the system and make it no longer usable.

HTTP Request

DELETE $serverUrl/api/policies/:id

URL Parameters

Parameter Description
ID The ID of the policy

Group Policies

Policies scoped to a specific group can also be managed at another endpoint.

curl "$serverUrl/api/groups/1/policies"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "policies": [
    {
      "id": 19,
      "name": "smallgroup max cores",
      "description": null,
      "policyType": {
        "id": 3,
        "code": "maxCores",
        "name": "Max Cores"
      },
      "zone": null,
      "site": {
        "id": 1,
        "name": "smallgroup"
      },
      "user": null,
      "refType": "ComputeSite",
      "refId": 1,
      "config": {
        "maxCores": 20
      },
      "enabled": true,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "accounts": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

HTTP Request

GET $serverUrl/api/groups/:groupId/policies

URL Parameters

Parameter Description
groupId The ID of the group

Cloud Policies

Policies scoped to a specific cloud can also be managed at another endpoint.

curl "$serverUrl/api/zones/1/policies"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "policies": [
    {
      "id": 19,
      "name": "bigcloud max cores",
      "description": null,
      "policyType": {
        "id": 3,
        "code": "maxCores",
        "name": "Max Cores"
      },
      "zone": {
        "id": 1,
        "name": "bigcloud"
      },
      "site": null,
      "user": null,
      "refType": "ComputeZone",
      "refId": 1,
      "config": {
        "maxCores": 1500
      },
      "enabled": true,
      "owner": {
        "id": 1,
        "name": "root"
      },
      "accounts": [

      ]
    }
  ],
  "meta": {
    "size": 1,
    "total": 1,
    "offset": 0,
    "max": 25
  }
}

HTTP Request

GET $serverUrl/api/zones/:cloudId/policies

URL Parameters

Parameter Description
cloudId The ID of the cloud

Environments

Provides API interfaces for managing the creation and modification of provisioning environments.

Get All Environments

curl "$serverUrl/api/environments"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "environments": [
    {
      "id": 1,
      "account": null,
      "code": "dev",
      "name": "Dev",
      "description": "Development",
      "visibility": null,
      "active": true,
      "sortOrder": 1,
      "dateCreated": "2016-08-27T19:26:09+0000",
      "lastUpdated": "2016-08-27T19:26:09+0000"
    },
    {
      "id": 2,
      "account": null,
      "code": "qa",
      "name": "Test",
      "description": "QA Test",
      "visibility": null,
      "active": true,
      "sortOrder": 2,
      "dateCreated": "2016-08-27T19:26:09+0000",
      "lastUpdated": "2016-08-27T19:26:09+0000"
    },
    {
      "id": 3,
      "account": null,
      "code": "staging",
      "name": "Staging",
      "description": "Staging",
      "visibility": null,
      "active": true,
      "sortOrder": 3,
      "dateCreated": "2016-08-27T19:26:09+0000",
      "lastUpdated": "2018-03-14T09:34:10+0000"
    },
    {
      "id": 4,
      "account": null,
      "code": "production",
      "name": "Production",
      "description": "Production",
      "visibility": null,
      "active": false,
      "sortOrder": 4,
      "dateCreated": "2016-08-27T19:26:09+0000",
      "lastUpdated": "2019-06-26T16:47:01+0000"
    }
  ],
  "meta": {
    "size": 4,
    "total": 5,
    "max": 25,
    "offset": 0
  }
}

This endpoint retrieves all environments.

HTTP Request

GET $serverUrl/api/environments

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Filter by matching name or code
name Filter by name
code Filter by code

Get a Specific Environment

curl "$serverUrl/api/environments/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "environment": {
    "id": 1,
    "account": null,
    "code": "dev",
    "name": "Dev",
    "description": "Development",
    "visibility": null,
    "active": true,
    "sortOrder": 1,
    "dateCreated": "2016-08-27T19:26:09+0000",
    "lastUpdated": "2016-08-27T19:26:09+0000"
  }
}

This endpoint will retrieve a specific environment by id

HTTP Request

GET $serverUrl/api/environments/:id

URL Parameters

Parameter Description
ID The ID of the environment

Create an Environment

curl -XPOST "$serverUrl/api/environments" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "name": "Dev B",
    "code": "devb",
    "description": "Our other dev team",
    "sortOrder": 4,
    "visibility": "private"
  }
}'

The above command returns JSON structured like getting a single environment:

HTTP Request

POST $serverUrl/api/environments

JSON Parameters

Parameter Default Description
name A unique name for the environment
code A unique code for the environment
description A description of the environment
visibility “private” private or public
sortOrder 0 Sort order

Updating an Environment

curl -XPUT "$serverUrl/api/environments/5" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "description": "The Dev B environment",
  }
}'

The above command returns JSON structured like getting a single environment:

HTTP Request

PUT $serverUrl/api/environments/:id

URL Parameters

Parameter Description
ID The ID of the environment

JSON Parameters

Parameter Default Description
name A unique name for the environment
description A description of the environment
visibility private or public
sortOrder Sort order
active Set to false to deactvate the environment

Only user created environments may be updated.

Toggle an Environment

curl -XPUT "$serverUrl/api/environments/5/toggle-active" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like getting a single environment:

HTTP Request

PUT $serverUrl/api/environments/:id/toggle-active

URL Parameters

Parameter Description
ID The ID of the environment

Query Parameters

Parameter Default Description
active (toggle) Pass true or false explicitly. Default is to toggle the current value.

Setting active to false will remove it from the list of available environments, making it unavailable during provisioning. This endpoint allows global environments to be updated by the master account.

Delete an Environment

curl -XDELETE "$serverUrl/api/environments/5" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/environments/:id

URL Parameters

Parameter Description
ID The ID of the environment

Only user created environments may be deleted.

Appliance Settings

Provides API interfaces for managing appliance settings within Morpheus.

Get Appliance Settings

curl "$serverUrl/api/appliance-settings" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "applianceSettings": {
    "applianceUrl": "http://foo.com",
    "internalApplianceUrl": "172.16.0.1",
    "corsAllowed": "bar.com",
    "registrationEnabled": true,
    "defaultRoleId": "2",
    "defaultUserRoleId": "4",
    "dockerPrivilegedMode": true,
    "passwordMinLength": "8",
    "passwordMinUpperCase": "1",
    "passwordMinNumbers": "1",
    "passwordMinSymbols": "1",
    "userBrowserSessionTimeout": "20",
    "userBrowserSessionWarning": "15",
    "expirePwdDays": "1000",
    "disableAfterAttempts": "100",
    "disableAfterDaysInactive": "2000",
    "warnUserDaysBefore": "10",
    "smtpMailFrom": "dan.devilbiss@gmail.com",
    "smtpServer": "smtp.gmail.com",
    "smtpPort": "465",
    "smtpSSL": true,
    "smtpTLS": true,
    "smtpUser": "dan.devilbiss@gmail.com",
    "smtpPassword": "************",
    "proxyHost": "proxy.com",
    "proxyPort": "8080",
    "proxyUser": "ddevilbiss",
    "proxyPassword": "************",
    "proxyDomain": "proxy.com",
    "proxyWorkstation": "work",
    "currencyProvider": "openexchange",
    "currencyKey": "1234",
    "enabledZoneTypes": [
      {
        "id": 12,
        "name": "Amazon"
      }
    ]
  }
}     

This endpoint retrieves appliance settings.

HTTP Request

GET $serverUrl/api/appliance-settings

Update Appliance Settings

curl -XPUT "$serverUrl/api/appliance-settings" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"applianceSettings": {
        "registrationEnabled": true,
        "applianceUrl": "http://10.0.2.2:8080/",
        "internalApplianceUrl": null,
        "corsAllowed": null,
        "dockerPrivilegedMode": true,
        "passwordMinLength": "8",
        "passwordMinUpperCase": "1",
        "passwordMinNumbers": "1",
        "passwordMinSymbols": "1",
        "userBrowserSessionTimeout": "20",
        "userBrowserSessionWarning": "15",
        "expirePwdDays": 30,
        "disableAfterAttempts": 5,
        "disableAfterDaysInactive": 90,
        "warnUserDaysBefore": 10,
        "smtpMailFrom": "stubby.toes@gmail.com",
        "smtpServer": "smtp.gmail.com",
        "smtpPort": 465,
        "smtpSSL": true,
        "smtpTLS": true,
        "smtpUser": "stubby.toes@gmail.com",
        "smtpPassword": "password",
        "proxyHost": null,
        "proxyPort": null,
        "proxyUser": "stubbytoes",
        "proxyPassword": "password",
        "proxyDomain": null,
        "proxyWorkstation": null,
        "currencyProvider": "openexchange",
        "currencyKey": null,
        "enableZoneTypes": [1, 2],
        "disableZoneTypes": [9],
        "defaultRoleId": 2,
        "defaultUserRoleId": 4
      }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/appliance-settings

JSON Parameters

Parameter Description
applianceUrl Appliance URL
internalApplianceUrl Internal Appliance URL (PXE)
corsAllowed API Allowed Origins
registrationEnabled Registration enabled (true, false)
defaultRoleId Default tenant role ID
defaultUserRoleId Default user role ID
dockerPrivilegedMode Docker privileged mode (true, false)
passwordMinLength Min Password Length
passwordMinUpperCase Min Password Uppercase
passwordMinNumbers Min Password Numbers
passwordMinSymbols Min Password Symbols
userBrowserSessionTimeout User Browser Session Timeout (Minutes)
dockerPrivilegedMode User Browser Session Warning (Minutes)
expirePwdDays Expire password after days. Setting to 0 disabled this feature
disableAfterAttempts Disable user after number of attempts. Set to 0 to disable this feature
disableAfterDaysInactive Disable user if inactive for specified days. Set to 0 to disable this feature
warnUserDaysBefore Send warning email number of days in advance before deactivating. Set to 0 to disable this feature
smtpFromEmail From email address
stmpServer SMTP server / host
smtpPort SMTP port
smtpSSL Use SSL for SMTP connection
smtpTLS Use TLS for SMTP connections
smtpUser SMTP username
smtpPassword SMTP password
proxyHost Proxy host
proxyPort Proxy port
proxyUser Proxy username
proxyPassword Proxy password
proxyDomain Proxy domain
proxyWorkstation Proxy workstation
currencyProvider Currency provider
currencyKey Currency provider API key
enableAllZoneTypes Set all cloud types enabled status on, overrides enableZoneTypes and disableZoneTypes parameters
enableZoneTypes List of cloud type IDs to set enabled status on
disableZoneTypes List of cloud type IDs to set enabled status off
disableAllZoneTypes Set all cloud types enabled status off, can be used in conjunction with enableZoneTypes

Toggle Maintenance Mode

curl -XPOST "$serverUrl/api/appliance-settings/maintenance?enabled=true" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/appliance-settings/maintenance

Query Parameters

Parameter Description
enabled Pass true to turn on maintenance mode, or false to turn it off. If no value is given then it will be toggled from off to on or vice versa.

This endpoint allows toggling the appliance maintenance mode.

Backup Settings

Provides API interfaces for managing backup settings within Morpheus.

Get Backup Settings

curl "$serverUrl/api/backup-settings" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "backupSettings": {
    "backupsEnabled": true,
    "createBackups": true,
    "backupAppliance": true,
    "defaultStorageBucket": {
      "id": 42,
      "name": "backups"
    },
    "defaultSchedule": {
      "id": 1,
      "code": "dailyAtMidnight",
      "name": "Daily at Midnight"
    },
    "retentionCount": 12
  }
}

This endpoint retrieves backup settings.

HTTP Request

GET $serverUrl/api/backup-settings

Update Backup Settings

curl -XPUT "$serverUrl/api/backup-settings" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"backupSettings": {
         "backupsEnabled": false,
         "createBackups": false,
         "backupAppliance": true,
         "retentionCount": 7,
         "updateExisting": false,
         "defaultSchedule": {
           "id": 2
         },
         "defaultStorageBucket": {
           "id": 44,
         }
      }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/backup-settings

JSON Parameters

Parameter Required Description
backupsEnabled N Use this to enable / disable scheduled backups
retentionCount N Maximum number of successful backups to retain
createBackups N Use this to enable / disable create backups
backupAppliance N When enabled, a Backup will be created to backup the Morpheus appliance database
updateExisting N Use this to update existing backups with new settings
defaultSchedule.id N ID of default backup schedule type
clearDefaultSchedule N Use this to clear existing default backup schedule
defaultStorageBucket.id N ID of default storage bucket
clearDefaultStorageBucket N Use this to clear default store bucket

Provisioning Settings

Provides API interfaces for managing provisioning settings within Morpheus.

Get Provisioning Settings

curl "$serverUrl/api/provisioning-settings" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "provisioningSettings": {
    "allowZoneSelection": true,
    "allowServerSelection": true,
    "requireEnvironments": true,
    "showPricing": true,
    "hideDatastoreStats": true,
    "crossTenantNamingPolicies": false,
    "reuseSequence": true,
    "cloudInitUsername": "root",
    "cloudInitPassword": "****",
    "cloudInitKeyPair": {
      "id": 3,
      "name": "stubby.toes"
    },
    "windowsPassword": null,
    "pxeRootPassword": null,
    "defaultTemplateType": {
      "id": 1,
      "name": "morpheus",
      "code": "morpheus"
    },
    "deployStorageProvider": {
      "id": 42,
      "name": "default-storage"
    }
  }
} 

This endpoint retrieves provisioning settings.

HTTP Request

GET $serverUrl/api/provisioning-settings

Update Provisioning Settings

curl -XPUT "$serverUrl/api/provisioning-settings" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
        "provisioningSettings": {
          "allowZoneSelection": true,
          "allowServerSelection": true,
          "requireEnvironments": true,
          "showPricing": true,
          "hideDatastoreStats": true,
          "crossTenantNamingPolicies": true,
          "reuseSequence": true,
          "cloudInitUsername": "stubbytoes",
          "cloudInitPassword": "supersecret",
          "deployStorageProvider": {
            "id": 42
          },
          "defaultTemplateType": {
            "id": 2
          }
        }
      }'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/provisioning-settings

JSON Parameters

Parameter Description
allowZoneSelection Use this to enable / disable allowing cloud selection
allowServerSelection Use this to enable / disable allowing host selection
requireEnvironments Use this to enable / disable requiring environment selection
showPricing Use this to enable / disable showing pricing
hideDatastoreStats Use this to enable / disable hiding datastore stats
crossTenantNamingPolicies Use this to enable / disable cross-tenant naming policies
reuseSequence Use this to enable / disable reusing naming sequence numbers
cloudInitUsername Cloud-init username
cloudInitPassword Cloud-init password
cloudInitKeyPair.id Cloud-init key pair ID
deployStorageProvider.id Deployment archive storage provider ID
windowsPassword Windows administrator password
pxeRootPassword PXE Boot default root password
defaultTemplateType.id Default blueprint type ID

Provisioning Licenses

Provides API interfaces for managing provisioning licenses within Morpheus. This allows configuration of which Windows license keys should be installed when provisioning your virtual images.

Get All Licenses

curl "$serverUrl/api/provisioning-licenses" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "licenses": [
    {
      "id": 1,
      "name": "2012 R2 Standard",
      "description": "2012 R2 Standard",
      "licenseType": {
        "id": 1,
        "code": "win",
        "name": "Windows"
      },
      "licenseKey": "*************************AB3E",
      "orgName": "Acme Motors",
      "fullName": "Bugs Bunny",
      "licenseVersion": "2012 R2 Standard",
      "copies": 1,
      "reservationCount": 0,
      "tenants": [

      ],
      "virtualImages": [
        {
          "id": 2021,
          "name": "Windows-Server-R2-AL"
        }
      ],
      "account": {
        "id": 1,
        "name": "Acme"
      }
    },
    {
      "id": 2,
      "name": "Microsoft Windows Server 2012 R2 Standard Evaluation",
      "description": "Microsoft Windows Server 2012 R2 Standard Evaluation",
      "licenseType": {
        "id": 1,
        "code": "win",
        "name": "Windows"
      },
      "licenseKey": "*************************A41H",
      "orgName": "Acme Motors",
      "fullName": "Yosemite Sam",
      "licenseVersion": "2012 R2 SE",
      "copies": 105,
      "reservationCount": 0,
      "tenants": [

      ],
      "virtualImages": [
        {
          "id": 2022,
          "name": "Windows-Server-R2-SE"
        }
      ],
      "account": {
        "id": 1,
        "name": "Acme"
      }
    }
  ],
  "meta": {
    "size": 2,
    "total": 2,
    "offset": 0,
    "max": 25
  }
}

This endpoint retrieves all licenses.

HTTP Request

GET $serverUrl/api/provisioning-licenses

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
sort name Sort order
direction asc Sort direction, use ‘desc’ to reverse sort
phrase Name, description, orgName, fullName restricts query to only load licenses which contain the phrase specified
name If specified will return an exact match on name
licenseType If specified will return an exact match on licenseType code
licenseVersion If specified will return an exact match on licenseVersion
orgName If specified will return an exact match on orgName
fullName If specified will return an exact match on fullName

Get a Specific License

curl "$serverUrl/api/provisioning-licenses/2" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "license": {
    "id": 2,
    "name": "2012 R2 Standard",
    "description": "2012 R2 Standard",
    "licenseType": {
      "id": 1,
      "code": "win",
      "name": "Windows"
    },
    "licenseKey": "*************************AB3E",
    "orgName": "Acme Motors",
    "fullName": "Bugs Bunny",
    "licenseVersion": "2012 R2 Standard",
    "copies": 1,
    "reservationCount": 0,
    "tenants": [

    ],
    "virtualImages": [
      {
        "id": 2021,
        "name": "Windows-Server-R2-AL"
      }
    ],
    "account": {
      "id": 1,
      "name": "Acme"
    }
  }
}

This endpoint retrieves a specific license.

HTTP Request

GET $serverUrl/api/provisioning-licenses/:id

URL Parameters

Parameter Description
id ID of the license

Get Reservations for Specific License

curl "$serverUrl/api/provisioning-licenses/2/reservations" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "licenses": [
    {
      "resourceId": 55,
      "resourceType": "ComputeServer",
    },
    {
      "resourceId": 56,
      "resourceType": "ComputeServer",
    }
  ]
}

This endpoint retrieves all reservations for a specific license. Each time a license is applied to a new server, a reservation is created, reducing the available copies for the license.

HTTP Request

GET $serverUrl/api/provisioning-licenses/:id/reservations

URL Parameters

Parameter Description
id ID of the license

Create a License

Use this command to create a new license.

curl -XPOST "$serverUrl/api/provisioning-licenses" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "license": {
    "name": "Test Windows",
    "licenseType": "win",
    "licenseKey": "12345-678-ABCDEFG-HIJKL",
    "orgName": "Acme Motors",
    "fullName": "Bugs Bunny",
    "licenseVersion": "2012 R2 Standard",
    "copies": 5,
    "description": "A windows key for testing",
    "virtualImages": [
      1,2,3
    ]
  }
}'

The above command returns JSON structured like getting a single license (abbreviated):

{
  "success": true,
  "license": {
    "id": 1
  }
}

HTTP Request

POST $serverUrl/api/provisioning-licenses

JSON Parameters

Parameter Required Description
name Y Name
licenseType Y License Type - The license type code. e.g. win
licenseKey Y License Key - The license key, to be kept a secret.
orgName N Org Name - The Organization Name (if applicable) related to the license key
fullName N Full Name - The Full Name (if applicable) related to the license key
licenseVersion N License Version
copies N Copies - The number of times the key can be used. Default is 1.
description N Description
virtualImages N Virtual Images - Array of Virtual Image IDs to associate with license.
tenants N Tenants - Array of tenants that are allowed to use the key.

Update a License

curl -XPUT "$serverUrl/api/provisioning-licenses/:id" \
  -H "Authorization: BEARER $accessToken"
  -H "Content-Type: application/json" \
  -d '{
    "license": {
      "name": "QA Windows Key",
      "copies": 5
    }
}'

The above command returns JSON structured like getting a single license (abbreviated):

{
  "success": true,
  "license": {
    "id": 1
  }
}

Use this command to update an existing license.

HTTP Request

PUT $serverUrl/api/provisioning-licenses/:id

URL Parameters

Parameter Description
id The ID of the license

JSON Parameters

Parameter Description
name Name
licenseVersion License Version
copies Copies - The number of times the key can be used.
description Description
virtualImages Virtual Images - Array of Virtual Image IDs to associate with license.
tenants Tenants - Array of tenants that are allowed to use the key.

Delete a License

curl -XDELETE "$serverUrl/api/provisioning-licenses/:id" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete a license.

HTTP Request

DELETE $serverUrl/api/provisioning-licenses/:id

URL Parameters

Parameter Description
id The ID of the license

Log Settings

Provides API interfaces for managing log settings within Morpheus.

Get Log Settings

curl "$serverUrl/api/log-settings" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "logSettings": {
    "enabled": true,
    "retentionDays": "1",
    "syslogRules": [
      {
        "id": 1,
        "name": "local",
        "rule": "*.* @@localhost:1234"
      }
    ],
    "integrations": []
  }
}

This endpoint retrieves log settings.

HTTP Request

GET $serverUrl/api/log-settings

Update Log Settings

curl -XPUT "$serverUrl/api/log-settings" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"logSettings": {
        "enabled": true,
        "retentionDays": 7,
        "syslogRules": [
          {
            "name": "local",
            "rule": "*.* @@localhost:4567"
          }
        ],
        "integrations": []
      }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/log-settings

JSON Parameters

Parameter Required Description
enabled N Use this to enable / disable logs
retentionDays N Availability time frame in days
syslogRules N Key for syslog rules list, see Syslog Rules
integrations N Key for integrations rules list, see Integrations

Syslog Rules

The syslogRules parameter is a list used for adding syslog forwarding rules to log settings.

Parameter Required Description
name Y Syslog name
rule Y Syslog rule, example: *.* @@server:port

Integrations

The integrations parameter is a list used for enabling / disabling integrations to log settings.

Parameter Required Description
name Y Integration name
enabled N Use this to enable / disable the integration. Host and port required when enabling.
host - Host of the integration, required when enabled is true
port - Port of the integration, required when enabled is true

Add Syslog Rule

curl -XPOST "$serverUrl/api/log-settings/syslog-rules" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{"syslogRule": {"name": "foo", "rule": "*.* @@bar.com:8080"}}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/log-settings/syslog-rules

JSON Parameters

Parameter Required Description
syslogRule.name Y Syslog name
syslogRule.rule Y Syslog rule, example: *.* @@server:port

Delete Syslog Rules

curl -XDELETE "$serverUrl/api/log-settings/syslog-rules/1" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structure like this:

{
  "success": true
}

Will delete the syslog rule matching the specified name.

HTTP Request

DELETE $serverUrl/api/log-settings/syslog-rules/:id

URL Parameters

Parameter Description
:id ID of the syslog rule

Whitelabel Settings

Provides API interfaces for managing whitelabel settings within Morpheus.

Get Whitelabel Settings

curl "$serverUrl/api/whitelabel-settings" \
  -H "Authorization: BEARER access_token"

The above command returns JSON structured like this:

{
  "whitelabelSettings": {
    "enabled": true,
    "applianceName": "My Appliance",
    "disableSupportMenu": false,
    "headerLogo": "http://10.0.2.2:8080/storage/uploads/uploads/ApplianceInstance/1/headerLogo/header_logo_original.png",
    "footerLogo": "http://10.0.2.2:8080/storage/uploads/uploads/ApplianceInstance/1/footerLogo/footer_logo_original.png",
    "loginLogo": "http://10.0.2.2:8080/storage/uploads/uploads/ApplianceInstance/1/loginLogo/login_logo_original.png",
    "favicon": "http://10.0.2.2:8080/storage/uploads/uploads/ApplianceInstance/1/favicon/favicon_original.ico",
    "headerBgColor": "#ffffff",
    "headerFgColor": "black",
    "navBgColor": "#ffffff",
    "navFgColor": "pink",
    "navHoverColor": "green",
    "primaryButtonBgColor": "red",
    "primaryButtonFgColor": "blue",
    "primaryButtonHoverBgColor": "orange",
    "primaryButtonHoverFgColor": "gray",
    "footerBgColor": "brown",
    "footerFgColor": "yellow",
    "loginBgColor": "aqua",
    "overrideCss": "div {\r\n    font-size: 16px;\r\n}",
    "copyrightString": "My copywriter",
    "termsOfUse": "These are my terms of use.",
    "privacyPolicy": "Here is my privacy policy.",
    "supportMenuLinks": [
      {
        "url": "http://helpmenu.com",
        "label": "Help",
        "labelCode": "help"
      }
    ]
  }
}    

This endpoint retrieves whitelabel settings.

HTTP Request

GET $serverUrl/api/whitelabel-settings

Update Whitelabel Settings

curl -XPUT "$serverUrl/api/whitelabel-settings" \
  -H "Authorization: BEARER access_token" \
  -H "Content-Type: application/json" \
  -d '{"whitelabelSettings": {
        "navBgColor": "#fff",
        "enabled": true,
        "applianceName": "My Appliance",
        "disableSupportMenu": false,
        "resetHeaderLogo": true,
        "resetFooterLogo": true,
        "resetLoginLogo": true,
        "resetFavicon": true,
        "headerBgColor": "#fff",
        "headerFgColor": "black",
        "navFgColor": "pink",
        "navHoverColor": "green",
        "primaryButtonBgColor": "red",
        "primaryButtonFgColor": "blue",
        "primaryButtonHoverBgColor": "orange",
        "primaryButtonHoverFgColor": "gray",
        "footerBgColor": "brown",
        "footerFgColor": "yellow",
        "loginBgColor": "cyan",
        "copyrightString": "My copywriter",
        "overrideCss": "div {\n    font-size: 16px;\n}",
        "termsOfUse": "These are my terms of use.",
        "privacyPolicy": "Here is my privacy policy.",
        "supportMenuLinks": [
          {
            "url": "http://helpme.com",
            "label": "Help Label",
            "labelCode": "help-code"
          },
          {
            "url": "http://helpmemore.com",
            "label": "Help More Label",
            "labelCode": "help-more-code"
          }
        ]
      }}'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

PUT $serverUrl/api/whitelabel-settings

JSON Parameters

Parameter Description
enabled Can be used to enable / disable whitelabel feature [true|false]
applianceName Appliance name. Master account only
disableSupportMenu Can be used to disable support menu [true|false]
resetHeaderLogo Resets header logo to default header logo [true|false]
resetFooterLogo Resets footer logo to default footer logo [true|false]
resetLoginLogo Resets login logo to default login logo [true|false]
resetFavicon Resets favicon to default favicon [true|false]
headerBgColor Header background color
headerFgColor Header foreground color
navBgColor Nav background color
navFgColor Nav foreground color
navHoverColor Nav hover color
primaryButtonBgColor Primary button background color
primaryButtonFgColor Primary button foreground color
primaryButtonHoverBgColor Primary button hover background color
primaryButtonHoverFgColor Primary button hover foreground color
footerBgColor Footer background color
footerFgColor Footer foreground color
loginBgColor Login background color
copyrightString Copyright String
overrideCss Override CSS
termsOfUse Terms of use content
privacyPolicy Privacy policy content
supportMenuLinks Support menu links. See Support Menu Links
Parameter Description
url URL to support menu link
label Label for support menu link
labelCode Label code for support menu link

Update Images

curl -XPOST "$serverUrl/api/whitelabel-settings/images" \
  -H "Authorization: BEARER access_token" \
  -F 'headerLogo.file=@filename.png;type=image/png' \
  -F 'footerLogo.file=@filename.png;type=image/png' \
  -F 'loginLogo.file=@filename.png;type=image/png' \
  -F 'favicon.file=@filename.ico;type=image/ico'

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

POST $serverUrl/api/whitelabel-settings/images

HTTP Headers

Header Description
Content-Type multipart/form-data is expected.

Parameters

Parameter Required Description
headerLogo.file N Header logo image file, valid image types [png|jpg|svg]
resetHeaderLogo N Resets header logo to default [true|false]
footerLogo.file N Footer logo image file, valid image types [png|jpg|svg]
resetFooterLogo N Resets footer logo to default [true|false]
loginLogo.file N Login logo image file, valid image types [png|jpg|svg]
resetLoginLogo N Resets login logo to default [true|false]
favicon.file N Favicon image file, valid image type ico
resetFavicon N Resets favicon logo to default [true|false]

Uploads whitelabel images. Expects multipart form data as the request format, not JSON.

Reset Image

curl -XDELETE "$serverUrl/api/whitelabel-settings/images/:imageType" \
  -H "Authorization: BEARER access_token" 

The above command returns JSON Structured like this:

{
  "success": true
}

HTTP Request

DELETE $serverUrl/api/whitelabel-settings/images/:imageType

Resets the specified image to the Morpheus default. See Valid Image Types

Valid Image Types

Download Image

curl -XGET "$serverUrl/api/whitelabel-settings/images/:imageType" \
  -H "Authorization: BEARER access_token" 

The above command returns binary output of the specified image

HTTP Request

GET $serverUrl/api/whitelabel-settings/images/:imageType

Downloads the specified image. See Valid Image Types

License

The License API can be used to view information about your currently installed license key, and install new licenses.

Get Current License

curl "$serverUrl/api/license" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "license": {
    "productTier": "enterprise",
    "startDate": "2018-03-08T00:00:00Z",
    "endDate": "2020-04-07T00:00:00Z",
    "maxInstances": 0,
    "maxMemory": 0,
    "maxStorage": 0,
    "hardLimit": false,
    "freeTrial": false,
    "multiTenant": true,
    "whitelabel": true,
    "reportStatus": true,
    "supportLevel": "standard",
    "accountName": "Master",
    "config": {
    },
    "features": {
      "dashboard": true,
      "guidance": true,
      "discovery": true,
      "analytics": true,
      "scheduling": true,
      "approvals": true,
      "usage": true,
      "activity": true,
      "instances": true,
      "apps": true,
      "templates": true,
      "automation": true,
      "virtualImages": true,
      "library": true,
      "migrations": true,
      "deployments": true,
      "groups": true,
      "clouds": true,
      "hosts": true,
      "network": true,
      "loadBalancers": true,
      "storage": true,
      "keyPairs": true,
      "sslCertificates": true,
      "boot": true,
      "backups": true,
      "cypher": true,
      "archives": true,
      "imageBuilder": true,
      "tenants": true,
      "plans": true,
      "pricing": true,
      "users": true,
      "userGroups": true,
      "monitoring": true,
      "logging": true,
      "monitoringServices": true,
      "loggingServices": true,
      "backupServices": true,
      "dnsServices": true,
      "codeService": true,
      "buildServices": true,
      "loadBalancerServices": true,
      "ipamServices": true,
      "approvalServices": true,
      "cmdbServices": true,
      "deploymentServices": true,
      "automationServices": true,
      "serviceDiscoveryServices": true,
      "identityServices": true,
      "trustServices": true
    },
    "zoneTypes": null,
    "lastUpdated": "2019-08-14T13:42:18Z",
    "dateCreated": "2019-08-14T13:42:18Z"
  },
  "currentUsage": {
    "memory": 12014876160,
    "storage": 177937354752,
    "workloads": 11
  }
}

This endpoint can be used to inspect the currently installed license.

HTTP Request

GET $serverUrl/api/license

HTTP Headers

Header Description
Authorization A valid access token

Install License

curl -XPOST "$serverUrl/api/license" \
  -H "Authorization: BEARER $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "license": "4704270b94ab7713e8eaca4c82917d27b5b2a1cc95a1818d71b4648c3f821a18a20b78ba9623f8609cbc3712b96fb4c68bbef1880c16a5946a198c1ff6943badef07458898df99b83cddca7bc33e883a54b6025fbd5b8e84d83c419d2ca5b7ec847227b2b63d1ccbcf6a91fcc9dc4e9bd26321166bb04e54983fc858c5c2f7c7893741f435f4921ba33a9778ec714a6a95054a074ff6969dda1b4"
}'

The above command returns JSON structured the same as Get License

HTTP Request

POST $serverUrl/api/license

HTTP Headers

Header Description
Authorization A valid access token
Content-Type application/json

JSON Parameters

Parameter Default Description
license License Key, an encrypted string that should be kept secret.

This endpoint installs a new license in the Morpheus appliance.

Test License

This endpoint can be used to decode a license to see if it is valid and inspect the license settings, such as who it belongs to and the enabled features. This is only a test, it does not install the key, or make any changes to your appliance.

curl -XPOST "$serverUrl/api/license/test" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "license": "4704270b94ab7713e8eaca4c82917d27b5b2a1cc95a1818d71b4648c3f821a18a20b78ba9623f8609cbc3712b96fb4c68bbef1880c16a5946a198c1ff6943badef07458898df99b83cddca7bc33e883a54b6025fbd5b8e84d83c419d2ca5b7ec847227b2b63d1ccbcf6a91fcc9dc4e9bd26321166bb04e54983fc858c5c2f7c7893741f435f4921ba33a9778ec714a6a95054a074ff6969dda1b4"
}'

The above command returns JSON structured the same as Get License

HTTP Request

POST $serverUrl/api/license/test

JSON Parameters

Parameter Default Description
license License Key, an encrypted string that should be kept secret.

Uninstall License

This endpoint will remove the currently installed license key. Be sure to have a copy of your license key saved before you uninstall it.

curl -XDELETE "$serverUrl/api/license" \
  -H "Authorization: Bearer $accessToken" \
  -H "Content-Type: application/json" \
  -d '{
  "license": "4704270b94ab7713e8eaca4c82917d27b5b2a1cc95a1818d71b4648c3f821a18a20b78ba9623f8609cbc3712b96fb4c68bbef1880c16a5946a198c1ff6943badef07458898df99b83cddca7bc33e883a54b6025fbd5b8e84d83c419d2ca5b7ec847227b2b63d1ccbcf6a91fcc9dc4e9bd26321166bb04e54983fc858c5c2f7c7893741f435f4921ba33a9778ec714a6a95054a074ff6969dda1b4"
}'

The above command returns JSON Structured like this:

{"success":true}

HTTP Request

DELETE $serverUrl/api/license

Ping

curl "$serverUrl/api/ping" \
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "success": true,
  "buildVersion": "4.2.2"
}

HTTP Request

GET $serverUrl/api/ping

This endpoint can be used to check the remote appliance build version and some other basic information.

This is an unsecured endpoint and does not require authorization. However, buildVersion will not be returned unless you are authenticated with a valid access token.

Search

curl "$serverUrl/api/search?phrase=dev"
  -H "Authorization: BEARER $accessToken"

The above command returns JSON structured like this:

{
  "hits": [
    {
      "id": "346",
      "uuid": "7c9f11a5-4630-4813-a3e7-65c2dfa0f20f",
      "name": "dev-test-1",
      "description": "A test dev instance",
      "type": "Instance",
      "dateCreated": "2020-09-15T20:24:30Z",
      "score": 20.0
    },
    {
      "id": "344",
      "uuid": "45edbae7-d433-4a9a-b82a-0adc5819d6ef",
      "name": "dev-test-2",
      "description": "Another test dev instance",
      "type": "Instance",
      "dateCreated": "2020-09-15T13:56:30Z",
      "score": 20.0
    }
  ],
  "query": "dev",
  "took": 12,
  "meta": {
    "offset": 0,
    "max": 25,
    "size": 2,
    "total": 2
  }
}

This endpoint provides global search for all types of objects, with the results sorted in order of relevance.

The phrase parameter value can be specified as part of the URL or as a query parameter. If phrase is not specified, then 0 results (hits) will be returned.

HTTP Request

GET $serverUrl/api/search/:phrase

URL Parameters

Parameter Description
:phrase Search phrase (query) to match results against

Query Parameters

Parameter Default Description
max 25 Max number of results to return
offset 0 Offset of records you want to load
phrase Search phrase to match results on
query Alias for phrase

Search Response JSON

Parameter Description
hits Array of search result objects
took Amount of time in milliseconds that the search took to execute.
meta Meta pagination object containing total count.

Search Result Object

Parameter Description
id ID of the object
uuid UUID of the object
name Name of the object
description Description of the object
type Type of object, eg. Instance, ComputeServer, ComputeSite, ComputeZone, User, Role, etc.
dateCreated Date the object was created
score Search score, higher means a better match to the specified phrase.

Setup

curl -XPOST "$serverUrl/api/setup/init" \
  -H "Content-Type: application/json" \
  -d '{
  "applianceName": "myappliance",
  "applianceUrl": "https://myappliance.morpheusdata.com",
  "accountName": "root",
  "username": "admin",
  "password": "69f49632b13e",
  "email": "admin@morpheusdata.com",
  "firstName": "Admin"

  }
}'

The above command returns JSON Structured like this:

{
  "success": true
}

This will initialize a freshly installed Morpheus appliance by creating the master Tenant and User.

Setup includes connecting to the Morpheus Hub. This is done either by registering a new account or logging in to an existing account, which connects your appliance to your organization’s hub account. By default, a community license key will be generated and installed in your new appliance.

If you choose not to connect to the hub, you will need to install a license key manually later on. A license can be installed using the Install License endpoint.

Some community builds of the Morpheus appliance will come with a pre-installed license, so you can skip the license install step.

The Ping api can be used to check if setup is needed or not, it returns a boolean flag called setupNeeded when the appliance is a fresh install and still needs to be setup.

HTTP Request

POST $serverUrl/api/setup/init

JSON Parameters

Parameter Default Description
applianceUrl Appliance URL
applianceName Appliance Name
accountName Master Account Name
username Username
password Password
email Email Address
firstName First Name
lastName Last Name
backups false Enable Backups
monitoring false Enable Monitoring
logs false Enable Logs
hubMode skip Hub Mode ie. register, login, skip. The default is skip, which means do not connect to the hub. Pass login or register to connect with the Morpheus Hub during setup.
hub Object containing Morpheus Hub connection settings. Either Hub Register Parameters or Hub Login Parameters. This is only required if hubMode is register or login.

Hub Register Parameters

Parameter Default Description
email Email Address of your new Morpheus Hub user.
password Password of your new Morpheus Hub user.
firstName First Name
lastName Last Name
jobTitle Job Title
companyName Company Name

These are the parameters for registering with the Morpheus Hub. This will create a new hub account.

Hub Login Parameters

Parameter Default Description
email Email Address of your Morpheus Hub user.
password Password of your Morpheus Hub user.

These are the parameters for logging into the Morpheus Hub account. This will link this appliance to your existing hub account.